From a7a6f0b6d4425655bfcaf1447019b8ddbf3e769d Mon Sep 17 00:00:00 2001 From: Roy Weesner Date: Mon, 27 Jul 2026 12:40:58 -0500 Subject: [PATCH] chore: sync technical-writer skill to latest version - Standardize admonitions on Docusaurus ::: syntax - Replace external check-links step with Docusaurus build-time link validation - Update API reference registration to Docusaurus sidebars (was mkdocs.yml) - Fix banned term dialog -> window in golden examples - Add opcon-parameter-descriptions.md resource (resolves broken SKILL.md reference) Co-Authored-By: Claude Opus 4.8 --- .claude/skills/technical-writer/SKILL.md | 85 +++++++--- .../resources/opcon-api-reference.md | 12 +- .../opcon-documentation-standards.md | 58 +++++-- .../resources/opcon-documentation-types.md | 17 +- .../resources/opcon-golden-examples.md | 40 ++++- .../resources/opcon-learner-roles.md | 27 ++++ .../resources/opcon-parameter-descriptions.md | 145 ++++++++++++++++++ .../resources/opcon-primary-analysis.md | 41 ++--- 8 files changed, 347 insertions(+), 78 deletions(-) create mode 100644 .claude/skills/technical-writer/resources/opcon-parameter-descriptions.md diff --git a/.claude/skills/technical-writer/SKILL.md b/.claude/skills/technical-writer/SKILL.md index a74931a..b9eb342 100644 --- a/.claude/skills/technical-writer/SKILL.md +++ b/.claude/skills/technical-writer/SKILL.md @@ -5,15 +5,15 @@ description: > user-facing documentation: API references, help articles, UI copy, parameter descriptions, setup instructions, or release notes. Enforces product voice, terminology, and formatting standards. +user-invocable: true allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task, WebFetch --- -> **Last updated:** April 2026 +> **Last updated:** July 2026 > > **Recent changes:** -> - Added Always-on scope section: standards now apply to all docs/ edits regardless of explicit skill invocation -> - Updated Document Types table to reflect correct repo paths (docs/ not docs-site/docs/) -> - Added overview page type to Document Types table +> - Added Resource Loading, Multi-Page Coordination, golden-examples.md +> - Added source-verification guardrails, Parameter Descriptions, Release Notes Requirement, and link validation guidance # Technical Writer @@ -29,18 +29,6 @@ When writing documentation, identify the primary audience by role. Use that role **General assumptions:** Readers are comfortable with automation and IT operations concepts (job scheduling, dependencies, agents, event-driven processing) but are NOT developers. Never expose internal class names, namespaces, or implementation details in user-facing text. -## Always-on scope - -These standards apply to **every edit or addition to any file in `docs/`**, regardless of whether the technical-writer skill was explicitly invoked. This includes targeted edits, bug fixes, content additions, new pages, and overview pages. - -Before completing any write or edit operation on a `docs/` file: - -1. Run the pre-flight checklist (see Quality Checklist below) against every sentence or section you touched -2. Verify that no banned terms, passive constructions, or heading case violations were introduced -3. If creating a new page, confirm it follows the correct documentation type structure from [opcon-documentation-types.md](resources/opcon-documentation-types.md) - -This rule cannot be overridden by operating mode or by the absence of an explicit skill invocation. If a change would violate these standards, fix the violation before saving — do not defer it to a later review pass. - ## Writing Process Before writing or reviewing any documentation page, complete these steps in order: @@ -81,6 +69,20 @@ mode and to every documentation type. - What source would resolve it (e.g., "check the controller validation logic" or "confirm with the development team") +5. **Verify UI labels and element types from source.** Before writing + any procedural step that references a UI element (button, menu, + field, tab, window), verify the element's exact label and type + from the source code (views, controllers, or JavaScript). Do not + assume element type or label from context. Common errors: calling + a menu item a "button," or using an approximate label instead of + the exact text displayed in the UI. + +6. **Read source code before writing.** Before writing documentation + for any feature, read the relevant source files to verify all + claims — workflows, field names, default values, UI labels, and + behavior. Do not write from memory, prior knowledge, or inference. + If the source cannot be located, flag the gap per Guardrail 3. + These guardrails exist because OpCon is used for mission-critical automation in financial institutions. Inaccurate documentation — even a fabricated default value or an invented workflow step — can @@ -95,7 +97,7 @@ When invoked, determine which mode applies: |---|---|---| | **Write** | "Write," "Create," "Draft" | Follow the full writing process. Produce complete output matching the documentation type template. | | **Review** | "Review," "Check," "Audit" | Compare existing content against all standards. Report violations with specific line references and suggested fixes. Do not rewrite unless asked. | -| **Edit** | "Fix," "Update," "Change," "Revise" | Apply targeted changes. Before applying, verify the proposed change does not violate the pre-flight checklist — do not remove required structural elements (such as the procedural lead-in sentence) while fixing other issues. Preserve existing structure and content that is already compliant. Only modify what is specified or what violates standards. | +| **Edit** | "Fix," "Update," "Change," "Revise" | Apply targeted changes. Before applying, verify the proposed change does not violate the pre-flight checklist — do not remove required structural elements (such as the procedural lead-in sentence) while fixing other issues. Preserve existing structure and content that is already compliant. Only modify what is specified or what violates standards. If the edit touches or is adjacent to documented UI labels, workflow steps, or described behavior, verify those elements from source code before applying changes to confirm the existing content is still accurate. | | **Consult** | "Should I," "What's the best way," "How do I" | Provide guidance by referencing the appropriate standard file. Do not produce documentation output unless asked. | ## Voice & Tone @@ -152,6 +154,16 @@ All documentation follows the rules in [opcon-documentation-standards.md](resour All step-by-step instructions follow the procedural rules and pattern library in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md). +## Parameter Descriptions + +User-facing parameter text follows [opcon-parameter-descriptions.md](resources/opcon-parameter-descriptions.md): + +- Boolean filters: "Results will include [items]." +- Boolean toggles: "[Feature] will be [enabled/applied]." +- Credentials: Brief clarifying note only if the name is ambiguous +- Never include "Optional:", "Recommended:", or "Required:" prefixes (auto-rendered by the UI) +- One sentence when possible; be specific about what changes + ## API Documentation When writing API endpoint reference docs, follow [opcon-api-reference.md](resources/opcon-api-reference.md) exactly. It defines the strict per-endpoint templates (GET list, GET detail, POST JSON, POST multipart), format rules, nesting notation, type vocabulary, and source material locations. Key constraints: @@ -170,6 +182,7 @@ When writing API endpoint reference docs, follow [opcon-api-reference.md](resour | [opcon-documentation-types.md](resources/opcon-documentation-types.md) | Documentation type definitions (conceptual, procedural, reference), structural templates, and combining guidance | | [opcon-glossary.md](resources/opcon-glossary.md) | Full terminology with definitions, "do not use" terms, and customer-facing alternatives | | [opcon-learner-roles.md](resources/opcon-learner-roles.md) | Audience profiles: who they are, knowledge domains, tone, scope, assumed knowledge per role | +| [opcon-parameter-descriptions.md](resources/opcon-parameter-descriptions.md) | Patterns for plugin parameter description text | | [opcon-api-reference.md](resources/opcon-api-reference.md) | Strict templates for API endpoint documentation | | [opcon-golden-examples.md](resources/opcon-golden-examples.md) | Complete reference examples for each documentation type — quality calibration for AI output | @@ -193,15 +206,17 @@ task to keep context focused and avoid unnecessary processing. | [opcon-documentation-types.md](resources/opcon-documentation-types.md) | Writing or reviewing a page (to identify structure). Skip for targeted edits where the page type is already clear. | | [opcon-golden-examples.md](resources/opcon-golden-examples.md) | Writing a new page from scratch (for quality calibration). Skip for reviews, edits, or consult mode. | | [opcon-api-reference.md](resources/opcon-api-reference.md) | The task involves API endpoint documentation | +| [opcon-parameter-descriptions.md](resources/opcon-parameter-descriptions.md) | The task involves plugin parameter description text | ## Document Types | Type | Location | Standards | |------|----------|-----------| | API endpoint reference | `docs/api/reference/` | opcon-api-reference.md | -| Help article | `docs/` | opcon-documentation-standards.md | -| Overview page | `docs/` (named `*-overview.md`) | opcon-documentation-standards.md + opcon-documentation-types.md | -| Release notes | `docs/release-notes.md` | opcon-documentation-standards.md (Release Notes section) | +| Help article | `docs-site/docs/` | opcon-documentation-standards.md | +| Release notes | `docs-site/docs/release-notes/` | opcon-documentation-standards.md (Release Notes section) | +| Parameter descriptions | Inline in plugin C# | opcon-parameter-descriptions.md | +| Setup instructions | Inline in plugin C# | opcon-documentation-standards.md | ## Multi-Page Coordination @@ -217,6 +232,7 @@ scope gaps, duplicated content, and broken cross-references. - One or more procedural pages (one per distinct task) - Reference entries if the feature introduces new settings, fields, or report types + - A release notes entry (see [Release Notes Requirement](#release-notes-requirement) below) 2. **Define scope boundaries.** For each page, state in one sentence what the page covers and what it intentionally excludes. If two @@ -241,6 +257,7 @@ scope gaps, duplicated content, and broken cross-references. ### Cross-Reference Rules +- **Always include a "Related topics" section** at the bottom of every page — when creating a new page, add it before finishing; when editing an existing page, review and update it as part of the task - Use "Related topics" sections at the bottom of each page — do not bury links mid-paragraph - Link text should match the target page's title exactly @@ -250,6 +267,25 @@ scope gaps, duplicated content, and broken cross-references. - When a procedure references a prerequisite procedure, link to it in a prerequisite note before the steps, not within the steps +## Release Notes Requirement + +Whenever documentation for a **new feature or improvement** is added, the release notes file must also be updated in the same task. + +**File:** `docs-site/docs/release-notes/whats-new.md` + +### How to update + +1. Open the release notes file and identify the correct section — **New features** for net-new capabilities, **Improvements** for enhancements to existing features. +2. Add a bullet under the appropriate subsection heading that matches the feature area (e.g., **Job Master**, **Schedules**, **Reports**, **System Configuration**). Create the subsection heading if it does not exist. +3. Write the bullet in this format: + - **[Action verb + what was added/changed].** [One to two sentences describing the value to the user and any key details.] For more information, see [page title](relative/link.md). +4. Use present tense and customer-facing terminology. Follow the same voice and formatting rules as all other documentation. +5. Do not summarize the feature exhaustively — the release note entry points to the full documentation page. + +**When to skip:** Do not add a release notes entry in these cases: +- The change is a correction to existing documentation (typo fixes, clarifications, restructuring) with no underlying product change. +- The documentation is new, but the feature it describes already shipped in a previous release. Writing documentation for a pre-existing, undocumented feature (such as an existing API endpoint's payload format) does not constitute a release event — the release notes for the version that introduced that feature, if any, have already been published. + ## Quality Checklist Before finalizing any documentation, run the full pre-flight checklist in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md). Quick summary: @@ -260,6 +296,7 @@ Before finalizing any documentation, run the full pre-flight checklist in [opcon - [ ] Action verbs follow the decision tree (Select, Go to, Press, Run, Enter, Clear) - [ ] No banned terms (click, execute, drop-down, icon, checkbox, hamburger, navigate to, etc.) - [ ] Steps are numbered, one action per step +- [ ] Numbered lists have two or more steps — single-action procedures use prose instead - [ ] Result statement present where applicable - [ ] No procedure exceeds ~10 steps without a section break - [ ] No internal class names, namespaces, or implementation details exposed @@ -268,6 +305,14 @@ Before finalizing any documentation, run the full pre-flight checklist in [opcon **Self-check:** After producing any documentation output, silently verify every item on the pre-flight checklist in [opcon-documentation-standards.md](resources/opcon-documentation-standards.md) before presenting it. If any item fails, fix it first — do not present output that knowingly violates these standards. +**Link validation:** Every internal link must point to a file that +exists and every cross-reference must resolve. Docusaurus validates +internal links at build time (via `onBrokenLinks` and +`onBrokenMarkdownLinks`) and fails the build on a broken link, so any +link that cannot resolve must be fixed before the page is committed. +When adding or changing a link, confirm the target file exists and the +relative path is correct. + ## When Uncertain - **Unknown term:** Search [opcon-glossary.md](resources/opcon-glossary.md) first. If not found, use the term as it appears in the UI and flag it for glossary review. diff --git a/.claude/skills/technical-writer/resources/opcon-api-reference.md b/.claude/skills/technical-writer/resources/opcon-api-reference.md index 58c0c72..2fa5207 100644 --- a/.claude/skills/technical-writer/resources/opcon-api-reference.md +++ b/.claude/skills/technical-writer/resources/opcon-api-reference.md @@ -225,21 +225,21 @@ These are non-negotiable. Every endpoint file must comply. 4. **Table/JSON parity.** Every field in a Sample Response/Request must have a corresponding row in its Attributes/Body table, and vice versa. The table and the JSON must be a 1:1 match. 5. **Nesting notation:** `field` for top-level, `parent.child` for nested objects, `items[].field` for array items, `items[].parent.child` for nested fields inside arrays. 6. **Type column values:** `string`, `integer`, `boolean`, `number`, `string (GUID)`, `string (ISO 8601)`, `array[string]`, `array[object]`, `object`. Be specific — prefer `string (GUID)` over `string` when the value is a GUID. -7. **Realistic sample data.** Use names, dates, and IDs plausible for a US financial institution workload automation environment. No "foo", "bar", "test", or "example.com". +7. **Realistic sample data.** Use names, dates, and IDs plausible for a US financial institution workload automation environment. No "foo", "bar", "test", or "example.com". Use **First Bank of Valkyrie** as the sample bank name and **firstbankofvalkyrie.com** as the sample email domain. 8. **No cross-references between files.** Each file is self-contained. 9. **camelCase JSON keys** matching `[JsonProperty]` attributes in DTOs. 10. **No commentary, design notes, or explanatory prose.** These are strict reference documents. -## mkdocs.yml Nav Registration +## Sidebar Registration -After creating an endpoint file, add it to the `nav` section of `mkdocs.yml` in **both** locations: +After creating an endpoint file, register it in the Docusaurus sidebar configuration (`sidebars.js`) in **both** navigation locations: -1. Under `API > API Reference > {Resource Group}` -2. Under `Reference > API Reference > {Resource Group}` +1. Under `API` > `API Reference` > `{Resource Group}` +2. Under `Reference` > `API Reference` > `{Resource Group}` If the resource group doesn't exist yet, create it in both locations. Group name = plural resource noun (e.g., "Jobs", "Schedules", "Agents"). Place the new group alphabetically among existing groups. -Nav entry format: `{Display Name}: api/reference/{filename}.md` +Sidebar entry format: reference the doc by its ID, `api/reference/{filename}` (no `.md` extension). ## Requirements diff --git a/.claude/skills/technical-writer/resources/opcon-documentation-standards.md b/.claude/skills/technical-writer/resources/opcon-documentation-standards.md index 1aa3bb7..58e9ffc 100644 --- a/.claude/skills/technical-writer/resources/opcon-documentation-standards.md +++ b/.claude/skills/technical-writer/resources/opcon-documentation-standards.md @@ -199,6 +199,7 @@ Rules for using "right-click": |---|---|---| | Button | Label + "button" | Select the **Save** button. | | Checkbox | Label + "option"; select/clear | Select the **Allow Multi-Instance** option. | +| Toggle | Label + "option"; for state-labeled toggles (e.g., "X is disabled" / "X is enabled"), use the full current-state label | Select the **Agent is disabled** option. | | Radio button | Label + "option" | Select the **Daily** option. | | Drop-down / list | Use "list", never "drop-down" | Select **Daily** from the list. | | Field | Exact label + "field" | In the **Job Name** field, enter the value. | @@ -210,6 +211,9 @@ Rules for using "right-click": | Hamburger menu | Never say "hamburger"; use label or "menu button" | Select the **OpCon** button in the top left corner. | | Ellipsis button | Tooltip name + (...) | Select the **More actions** (...) button. | | Expander arrow | Label + appropriate element; never say "arrow" or "drop-down arrow" | Select the **Frequency** button and pick **Add** from the list. | +| Overlay / popup panel | "window" | The **Add Job** window is displayed. | +| Wizard step | Step name + "step" | The **Frequency** step is displayed. | +| Full page / route destination | "page" | The **Job Master** page is displayed. | ### Banned UI Terminology @@ -218,12 +222,16 @@ Never use these terms in documentation: - **drop-down** (any variation) — use "list" or "field" - **icon** — treat as a button if it performs an action - **checkbox** — use "option" +- **toggle** — use "option" (include any state qualifier in the label, e.g., "is disabled" / "is enabled") - **radio button** — use "option" - **hamburger** — use label or "menu button" - **arrow** or **drop-down arrow** — use the label + appropriate element - **text box** — use "field" or "area" - **menu item** — refer to the item by name - **navigation** (as a noun for a menu) — use "menu" +- **dialog** or **dialog box** — use "window" +- **modal** — use "window" +- **screen** (as a name for a UI element) — use "page", "step", "window", or "area" depending on what it is; "screen" is acceptable only when referring to the physical display (e.g., "on screen", "screen recording") --- @@ -337,18 +345,24 @@ Mark optional steps explicitly: Use tables when users must choose between options within a step. - Introduce the table in the step text -- Indent the table to align with the step it belongs to +- Indent the table — and any note preceding the table — with **4 spaces** to keep them attached to the step in Docusaurus +- Do **not** add a continuation sentence after the table — include result information in the step lead-in text or in the following step's result statement - Always explain the **consequences** of each option ```markdown 2. Select one of the following options: - | Option | Description | - |---|---| - | Copy a Job | Creates a new job by copying an existing one. Frequencies, dependencies, and events are duplicated. | - | Create a New Job | Creates a new job from scratch. You will need to configure all settings manually. | + :::note + Both options create the job immediately. Choose based on whether + you want to reuse an existing job's configuration. + ::: -3. Select the **Save** button. + | Option | Use when | + |---|---| + | **Copy a Job** | You want to reuse an existing job's frequencies, dependencies, and events | + | **Create a New Job** | You want to configure all settings manually | + +3. Select the **Save** button. The job is added to the Job Master. ``` ### Linking to Other Procedures @@ -458,16 +472,18 @@ Use callouts sparingly and intentionally. Three tiers: | Caution | **CAUTION:** followed by the text | Risk of data, system, or configuration issues | | Warning | **WARNING:** in all caps, bold | High risk of serious damage or data loss | -### In Zensical / MkDocs Markdown +### In Markdown -Use admonition syntax: +Use Docusaurus admonition syntax: ```markdown -!!! note - This information can be found at help.smatechnologies.com. +:::note +This information can be found at help.smatechnologies.com. +::: -!!! warning - Not completing a backup prior to these steps could result in data loss. +:::warning +Not completing a backup prior to these steps could result in data loss. +::: ``` ### In Plugin Instructions (C# Inline) @@ -475,11 +491,19 @@ Use admonition syntax: Use heading syntax indented under the relevant step: ```csharp -.AppendLine("3. Select **Reset My Security Token**.") -.AppendLine(" ###### Tip: The token is sent to your registered email.") +.AppendLine("3. Select **Add Machine**.") +.AppendLine(" ###### Tip: The machine name must match the agent's configured name.") ``` ---- +### Placement + +Place a callout immediately before the content it relates to: + +- **Applies to a specific step decision** (e.g., which option to choose from a table) → indent it within that step, before the table, at 4 spaces +- **Applies to the entire procedure** → place it before the opening "To [goal], complete the following steps:" sentence +- **Applies to a post-procedure result** → place it after the final result statement + +Never append callouts at the end of a procedure unless they describe something that occurs after all steps are complete. A callout placed after the last step that informs a decision in an earlier step is in the wrong place. ## Images @@ -700,6 +724,7 @@ Before finalizing any documentation, verify: - [ ] Opens with "To [goal], complete the following steps:" - [ ] One action per step - [ ] Steps are numbered sequentially +- [ ] Numbered lists have two or more steps — single-action procedures use prose instead of a numbered list - [ ] Ends with a result statement - [ ] No procedure exceeds ~10 steps without a section break - [ ] Tables in procedures explain consequences of each option @@ -713,11 +738,12 @@ Before finalizing any documentation, verify: - [ ] No instance of "navigate to" (use "go to") - [ ] No instance of "drop-down" (use "list" or "field") - [ ] No instance of "icon" (treat as button) -- [ ] No instance of "checkbox" or "radio button" (use "option") +- [ ] No instance of "checkbox", "toggle", or "radio button" (use "option") - [ ] No instance of "hamburger" - [ ] No instance of "text box" (use "field" or "area") - [ ] No instance of "client" (use "customer") - [ ] No instance of "launch" (use "open" or "start") +- [ ] No instance of "screen" used as a UI element name (use "page", "step", "window", or "area") --- diff --git a/.claude/skills/technical-writer/resources/opcon-documentation-types.md b/.claude/skills/technical-writer/resources/opcon-documentation-types.md index c3e6a27..65fa285 100644 --- a/.claude/skills/technical-writer/resources/opcon-documentation-types.md +++ b/.claude/skills/technical-writer/resources/opcon-documentation-types.md @@ -131,8 +131,9 @@ not built for that day. [1–2 sentences: what this procedure accomplishes and when to use it.] -!!! note "Prerequisite" - [What must be completed before starting.] +:::note[Prerequisite] +[What must be completed before starting.] +::: To [accomplish goal], complete the following steps: @@ -153,8 +154,9 @@ To [accomplish goal], complete the following steps: Use this procedure to add a new automated job to an existing schedule. Repeat this procedure for each job that needs to be added. -!!! note "Prerequisite" - The schedule must exist before adding jobs. See [Create a Schedule]. +:::note[Prerequisite] +The schedule must exist before adding jobs. See [Create a Schedule]. +::: To add a job, complete the following steps: @@ -175,6 +177,13 @@ To add a job, complete the following steps: ## 3. Reference Documentation +> For plugin parameter descriptions specifically, consult +> [opcon-parameter-descriptions.md](opcon-parameter-descriptions.md) which provides +> patterns tailored to the OpCon UI rendering format. +> For API endpoint documentation, do NOT use the reference template +> below. Instead follow the strict per-endpoint templates in +> [opcon-api-reference.md](opcon-api-reference.md). + **Purpose:** Provide factual information that readers need to look up quickly. Organized for scanning, not reading start to finish. **When to use:** UI element descriptions, field/setting definitions, report descriptions, plugin lists, API documentation, glossaries, system requirements, and any factual lookup content. diff --git a/.claude/skills/technical-writer/resources/opcon-golden-examples.md b/.claude/skills/technical-writer/resources/opcon-golden-examples.md index 474afae..cd6d2ab 100644 --- a/.claude/skills/technical-writer/resources/opcon-golden-examples.md +++ b/.claude/skills/technical-writer/resources/opcon-golden-examples.md @@ -98,9 +98,10 @@ Add a frequency to a job to specify when OpCon should build and run it. A job without a frequency will not be built into the daily schedule. -!!! note "Prerequisite" - The job must exist in the Job Master before a frequency can be - added. See [Add a job to a schedule](add-job.md). +:::note[Prerequisite] +The job must exist in the Job Master before a frequency can be +added. See [Add a job to a schedule](add-job.md). +::: To add a frequency, complete the following steps: @@ -108,16 +109,17 @@ To add a frequency, complete the following steps: 2. In the **Schedule** list, select the schedule. 3. Select the job. The Job Master Details page is displayed. 4. Select the **Frequency** tab. -5. Select the **Add** button. The Add Frequency dialog is displayed. +5. Select the **Add** button. The **Add Frequency** window is displayed. 6. In the **Frequency Name** field, select an existing frequency from the list or enter a name to create a new one. 7. Configure the frequency options. 8. Select the **Save** button. The frequency is added to the job. -!!! tip - Select the **Forecast** button to preview which dates the - frequency will generate before saving. This is especially useful - when holiday calendar offsets are involved. +:::tip +Select the **Forecast** button to preview which dates the +frequency will generate before saving. This is especially useful +when holiday calendar offsets are involved. +::: **Related topics:** @@ -128,6 +130,28 @@ To add a frequency, complete the following steps: --- +## Procedural Pattern: Inline Note with Table + +When a step requires the user to choose between options and there is relevant context to share before they choose, place the note inside the step before the table. Indent both the note and the table at 4 spaces to keep them attached to the step in Docusaurus. + +```markdown +2. Select the build option you need: + + :::note + Both options create the job immediately. Choose based on whether + you want to reuse an existing job's configuration. + ::: + + | Option | Use when | + |---|---| + | **Copy a Job** | You want to reuse an existing job's frequencies, dependencies, and events | + | **Create a New Job** | You want to configure all settings manually | + +3. Select the **Save** button. The job is added to the Job Master. +``` + +--- + ## Reference Example Target audience: Compliance Team and Operations Staff (scanning for specific information) diff --git a/.claude/skills/technical-writer/resources/opcon-learner-roles.md b/.claude/skills/technical-writer/resources/opcon-learner-roles.md index be06aa7..05a58b3 100644 --- a/.claude/skills/technical-writer/resources/opcon-learner-roles.md +++ b/.claude/skills/technical-writer/resources/opcon-learner-roles.md @@ -4,6 +4,8 @@ Guidelines for understanding the roles within OpCon. Use these guidelines to pro ## Section Reference +Each role description includes the following sections: + | Section | Purpose | |---------|---------| | Who they are | Understand the audience and correctly describe the role in documentation | @@ -209,3 +211,28 @@ When writing documentation, identify the primary audience by role. Use that role **Tone adjustment:** Evidence-focused audience. They care about what the system can prove, not how it works. Connect every report or log to what it demonstrates from a compliance standpoint. Use plain language and avoid internal OpCon jargon. Precision matters — document exactly what each report contains and what it does and does not show. **Assume they understand:** The regulatory landscape for financial institutions (FFIEC, FDICIA, NCUA, SOX), what an audit trail is and why it matters, and the general concepts of operational risk and control frameworks. Do not assume they understand OpCon configuration, job type specifics, or automation design principles. + +--- + +## Universal (All Roles) + +This is not a separate role — readers don't self-identify as "Universal." It is an **audience designation** the writer chooses when no single role applies. + +**When to use:** +- Content is conceptual, introductory, or provides an overview — the reader's specific OpCon role doesn't change what they need to know +- Source material is a product overview, feature introduction, or foundational explainer intended for any OpCon user +- The institution has combined roles and the reader's specific role is unknown (e.g., one person configures jobs, monitors schedules, and resolves failures) +- The page is first-contact or getting-started content — the reader may not yet know which OpCon role applies to them + +**When NOT to use:** +- Any procedural content where workflow steps, UI access, or available actions depend on the reader's OpCon role +- Content that requires domain knowledge specific to a single role (e.g., how to build a job, how to configure a frequency, how to set up an agent) +- Any content where the operational or compliance stakes differ by role — use the role with the highest stakes instead + +**Assumed knowledge:** None beyond basic financial institution operations. No OpCon terminology, no automation concepts, and no prior product exposure assumed. If a reader has never opened OpCon, they should be able to follow Universal content without stopping to ask what a word means. + +**Tone:** Patient, foundational, welcoming. Lead with a business need the reader already recognizes — something that happens at their institution regardless of which software they use. Follow with how OpCon addresses it. Define every OpCon term the first time it appears. No jargon without explanation. + +**Pitch level:** Use Business Analyst as the floor. If a Business Analyst — one of the least technical OpCon audiences — would follow it without confusion, all roles will. + +**Note on combined roles:** In smaller financial institutions, one person often holds multiple OpCon roles simultaneously — configuring the system, monitoring schedules, and resolving job failures. Universal content serves this reader without requiring them to identify which hat they are wearing at any given moment. The content should be relevant and meaningful regardless of where they sit in the workflow. diff --git a/.claude/skills/technical-writer/resources/opcon-parameter-descriptions.md b/.claude/skills/technical-writer/resources/opcon-parameter-descriptions.md new file mode 100644 index 0000000..c00fd35 --- /dev/null +++ b/.claude/skills/technical-writer/resources/opcon-parameter-descriptions.md @@ -0,0 +1,145 @@ +# Parameter Descriptions + +> For writing and formatting standards, see +> [opcon-documentation-standards.md](opcon-documentation-standards.md). + +Guidelines for writing clear, consistent descriptions for plugin parameter definitions. + +## Parameter Object Overview + +Each parameter in a plugin consists of the following components: + +| Component | Purpose | +|-----------|---------| +| Id | Unique identifier for the parameter | +| Name | User-facing label displayed in the UI | +| Description | Explanatory text describing the parameter's effect | +| Type | The data type and input control used | +| Optionality | Whether the parameter is required, recommended, or optional | + +### Parameter Types + +| Type | Use Case | +|------|----------| +| Boolean | Checkbox for yes/no options (most common) | +| Text | Single-line text input | +| TextArea | Multi-line text input | +| Password | Masked text input for sensitive values | +| Hidden | Stored value not displayed to users | +| Image | Image upload (rare) | + +### Optionality Levels + +| Level | Meaning | Display | +|-------|---------|---------| +| Required | Must be provided for the plugin to function | Shown with "Required:" prefix | +| Recommended | Strongly suggested but not mandatory | Shown with "Recommended:" prefix | +| Optional | Can be omitted; plugin works without it | Shown with "Optional:" prefix | + +The optionality prefix is auto-rendered in the UI based on the parameter's optionality level - do not include it in the description text. + +## Quick Reference + +| Parameter Type | Pattern | Example | +|----------------|---------|---------| +| Boolean filter | Results will include [items]. | Results will include jobs currently on hold. | +| Boolean toggle | [Action/Feature] will be [enabled/applied]. | Connection will use the test environment. | +| Boolean option | Select this option to [action]. | Select this option to include sub-schedule jobs. | +| Credential | Brief clarifying note. | The service account used to authenticate to the API. | +| Configuration | Defines/Specifies [what it sets]. | Defines the beginning of the date range for filtered results. | + +## When to Include Descriptions + +**Include descriptions when:** +- The parameter name alone is ambiguous +- Users need context about the effect +- There are important caveats or notes + +**Omit descriptions when:** +- The parameter name is self-explanatory (e.g., "Username", "Password") +- The purpose is obvious from context + +## Description Patterns + +### Boolean Filter Parameters +Use when the parameter includes/excludes items in results: + +| Name | Description | +|------|-------------| +| Held Jobs | Results will include jobs currently on hold. | +| Completed Jobs | Results will include jobs that have finished successfully. | +| Include Sub-Schedules | Results will include jobs from nested sub-schedules. | + +### Boolean Toggle Parameters +Use when the parameter enables a feature or behavior: + +| Name | Description | +|------|-------------| +| Use Test Environment | Connection will use the test environment. | +| Suppress Notifications | Job status notifications will be suppressed. | + +### Boolean Option Parameters +Use "Select this option to..." for clarity: + +| Name | Description | +|------|-------------| +| Include Offline Machines | Select this option to include machines that are currently offline. | +| Include Run History | Select this option to include prior job run history. | + +### Credential Parameters +Keep brief; clarify only when needed: + +| Name | Description | +|------|-------------| +| API Token | The token used to authenticate to the service. | +| Service Account | The account under which the connection runs. | +| Client Secret | (Often omitted - self-explanatory) | + +### Configuration Parameters +Use "Defines" or "Specifies" for required settings: + +| Name | Description | +|------|-------------| +| Hostname | Defines the server address for the connection. | +| Search Scope | Specifies which schedules will be searched. | + +## Writing Guidelines + +### Do +- Use present tense or future tense consistently +- Start Boolean filter descriptions with "Results will include..." +- Keep descriptions to one sentence when possible +- Be specific about what gets included, excluded, or changed +- Use consistent terminology across similar parameters + +### Don't +- Include "Optional:" or "Required:" prefixes (auto-rendered based on optionality level) +- Use ambiguous terms like "may" or "might" - be definitive +- Add implementation details unless relevant to users +- Use bullet points or special formatting within descriptions +- Repeat information already conveyed by the parameter name + +### Common Mistakes + +❌ "Optional: Results will include held jobs." (don't add Optional prefix) +❌ "This might include offline machines." (don't use "might" — be definitive) +❌ "Include Held Jobs: Select this option to include held jobs." (redundant — don't repeat the parameter name) + +## Caveats and Notes + +For important context, append to the description: + +``` +Include Sub-Schedules +Results will include jobs from nested sub-schedules. Note: Including sub-schedules can significantly increase the size of the result set. +``` + +## Checklist + +- [ ] Description explains the parameter's effect, not its requirement +- [ ] Uses consistent tense (present or future) +- [ ] No "Optional:/Required:" prefixes (auto-rendered based on optionality level) +- [ ] One sentence when possible +- [ ] Specific about what changes when parameter is set +- [ ] No redundant information from parameter name +- [ ] Important caveats included when relevant diff --git a/.claude/skills/technical-writer/resources/opcon-primary-analysis.md b/.claude/skills/technical-writer/resources/opcon-primary-analysis.md index f8a6c29..ba6fe13 100644 --- a/.claude/skills/technical-writer/resources/opcon-primary-analysis.md +++ b/.claude/skills/technical-writer/resources/opcon-primary-analysis.md @@ -1,6 +1,6 @@ # Writer-Friendly Documentation Standard -> **Purpose:** This file defines the primary page template used to evaluate documentation completeness and structure. Every feature page submitted for review is scored against these 11 active sections (0–1, 4–12). Sections 2 and 3 are deprecated — their content is now part of Section 1. +> **Purpose:** This file defines the primary page template used to evaluate documentation completeness and structure. Every feature page submitted for review is scored against these 13 sections (0–12). > > **Used by:** `doc-quality-assessor` — Template Adherence Review (Step 3) and Completeness subscore. @@ -8,14 +8,14 @@ ## Template Overview -Every feature page must include all 11 active sections below, in order. Each section has a defined intent — use it to judge whether the content present actually fulfills the section's purpose, not just whether a heading exists. +Every feature page must include all 13 sections below, in order. Each section has a defined intent — use it to judge whether the content present actually fulfills the section's purpose, not just whether a heading exists. | # | Section Title | One-Line Intent | |---|---|---| | 0 | Theme and Audience | Declares page type and target reader at the top | -| 1 | What Is It? (Overview, Use Cases, and Value) | Prose description + bullet list of scenarios and benefits | -| ~~2~~ | ~~When Would You Use It?~~ | **Deprecated** — merge content into § 1 | -| ~~3~~ | ~~Why Would You Use It?~~ | **Deprecated** — merge content into § 1 | +| 1 | What Is It? (Overview) | 2–4 sentence intro for a first-time reader | +| 2 | When Would You Use It? (Use Cases) | Bullet list of key scenarios | +| 3 | Why Would You Use It? (Value) | Benefits in plain language | | 4 | How To Implement It | Prerequisites, numbered steps, one example | | 5 | Configuration Options | Table: Setting \| What It Does \| Default \| Notes | | 6 | Exception Handling | Error → Meaning → Fix | @@ -47,32 +47,27 @@ At the top of the page, clearly state: --- -### Section 1 — What Is It? (Overview, Use Cases, and Value) +### Section 1 — What Is It? (Overview) -A combined section that explains what the feature is, when readers would use it, and why it provides value. Structure it as: +2–4 sentences explaining the feature for a first-time reader. Should answer: what does this feature do, and what problem does it solve? -1. **Prose description** (1–3 sentences): what this feature does and what problem it solves. Written for a first-time reader. -2. **Bullet list** (at least 2 bullets): key use-case scenarios and/or benefits. Phrased from the reader's perspective — either as scenarios ("Use this when...", "You are configuring...") or as outcomes ("Reduces...", "Ensures..."). Do not include bullets that simply restate the prose description. - -Do not use subheadings inside this section. Do not create separate `## When would you use it?` or `## Why would you use it?` headings — those are deprecated. - -**Evaluation pass criteria:** Prose description present (1–3 sentences). At least 2 bullets present. No deprecated When/Why subheadings. No redundancy between prose and bullets. +**Evaluation pass criteria:** 2–4 sentences present. No bullet lists. Written for someone with no prior exposure to the feature. --- -### Section 2 — ~~When Would You Use It?~~ (DEPRECATED) +### Section 2 — When Would You Use It? (Use Cases) -> **This section is deprecated.** Do not create a `## When would you use it?` heading on any new or revised page. Merge existing When content into the bullet list under § 1 (What Is It?) and remove the heading. -> -> When reviewing existing pages: flag any `## When would you use it?` section as a violation and suggest merging its bullets into § 1. +A bullet list of key scenarios in which a user would reach for this feature. Each bullet should describe a real situation, not a capability. + +**Evaluation pass criteria:** At least 2 bullets present. Phrased as scenarios ("When you need to…", "If your organization…"), not capabilities ("This feature supports…"). --- -### Section 3 — ~~Why Would You Use It?~~ (DEPRECATED) +### Section 3 — Why Would You Use It? (Value) -> **This section is deprecated.** Do not create a `## Why would you use it?` heading on any new or revised page. Merge existing Why content into the bullet list under § 1 (What Is It?) and remove the heading. -> -> When reviewing existing pages: flag any `## Why would you use it?` section as a violation and suggest merging its bullets into § 1. +Benefits written in plain language. Focus on outcomes: easier, faster, safer, more automated, reduced risk, etc. Avoid marketing language. + +**Evaluation pass criteria:** At least 2 distinct benefits stated. Written from the reader's perspective. Does not simply restate the feature's capabilities. --- @@ -188,8 +183,6 @@ When evaluating a page against this template, apply the following status to each | ⚠️ Present but incomplete | Section exists but is missing one or more required elements | | ❌ Missing | Section is absent or reduced to a heading with no content | -The **Completeness subscore** (weighted 25%) is derived from the ratio of ✅ sections to the 11 active sections (0–1, 4–12). Sections 2 and 3 are excluded from scoring — their presence is a violation, not a credit. +The **Completeness subscore** (weighted 25%) is derived from the ratio of ✅ sections to total sections. Partial credit applies for ⚠️ sections at the reviewer's discretion. The **Structure / Template Adherence subscore** (weighted 15%) evaluates whether sections appear in order, use the correct format (table, numbered list, etc.), and meet the structural requirements stated above — not just whether content is present. - -**Violation: deprecated headings present.** If a page contains `## When would you use it?` or `## Why would you use it?` as standalone headings, flag each as a structure violation and recommend merging the content into § 1.