Documentation writer

This skill provides standards for writing, reviewing, and editing documentation.

Phase 1: Documentation standards

Adhere to these principles when writing, editing, and reviewing documentation.

Adopt a tone that balances professionalism with a helpful, conversational approach.

Perspective and tense: Address the reader as "you." Use active voice and present tense (for example, "The API returns...").
Tone: Professional, friendly, and direct.
Clarity: Use simple vocabulary. Avoid jargon, slang, and marketing hype.
Global audience: Write in standard US English. Avoid idioms and cultural references.
Requirements: Be clear about requirements ("must") vs. recommendations ("we recommend"). Avoid "should."
Word choice: Avoid "please" and anthropomorphism (for example, "the server thinks"). Use contractions (don't, it's).

Write precisely to ensure your instructions are unambiguous.

Abbreviations: Avoid Latin abbreviations; use "for example" (not "e.g.") and "that is" (not "i.e.").
Punctuation: Use the serial comma. Place periods and commas inside quotation marks.
Dates: Use unambiguous formats (for example, "January 22, 2026").
Conciseness: Use "lets you" instead of "allows you to." Use precise, specific verbs.
Examples: Use meaningful names in examples; avoid placeholders like "foo" or "bar."

Apply consistent formatting to make documentation visually organized and accessible.

Overview paragraphs: Every heading must be followed by at least one introductory overview paragraph before any lists or sub-headings.
Text wrap: Wrap text at 80 characters (except long links or tables).
Casing: Use sentence case for headings, titles, and bolded text.
Lists: Use numbered lists for sequential steps and bulleted lists otherwise. Keep list items parallel in structure.
UI and code: Use bold for UI elements and code font for filenames, snippets, commands, and API elements. Focus on the task when discussing interaction.
Links: Use descriptive anchor text; avoid "click here." Ensure the link makes sense out of context.
Accessibility: Use semantic HTML elements correctly (headings, lists, tables).
Media: Use lowercase hyphenated filenames. Provide descriptive alt text for all images.

Follow these structural guidelines:

BLUF: Start with an introduction explaining what to expect.
Experimental features: If a feature is clearly noted as experimental, add the following note immediately after the introductory paragraph: > **Note:** This is a preview feature currently under active development.
Headings: Use hierarchical headings to support the user journey.
Procedures:
- Introduce lists of steps with a complete sentence.
- Start each step with an imperative verb.
- Number sequential steps; use bullets for non-sequential lists.
- Put conditions before instructions (for example, "On the Settings page, click...").
- Provide clear context for where the action takes place.
- Indicate optional steps clearly (for example, "Optional: ...").
Elements: Use bullet lists, tables, notes (> **Note:**), and warnings (> **Warning:**).
Avoid table of contents: If a table of contents is present, remove it.
Next steps: Conclude with a "Next steps" section if applicable.

Before modifying any documentation, thoroughly investigate the request and the surrounding context.

Clarify: Understand the core request. Differentiate between writing new content and editing existing content. If the request is ambiguous (for example, "fix the docs"), ask for clarification.
Investigate: Examine relevant code for accuracy.
Audit: Read the latest versions of relevant files in apps/docs/.
Connect: Identify all referencing pages if changing behavior.
Plan: Create a step-by-step plan before making changes.

Implement your plan by either updating existing files or creating new ones.

Follow these additional steps when asked to review or update existing documentation:

Gaps: Identify areas where the documentation is incomplete or no longer reflects existing code.
Structure: Apply structure rules (BLUF, headings, etc.) when adding new sections to existing pages.
Tone: Ensure the tone is active and engaging. Use "you" and contractions.
Clarity: Correct awkward wording, spelling, and grammar. Rephrase sentences to make them easier for users to understand.
Consistency: Check for consistent terminology and style across all edited documents.

Perform a final quality check to ensure that all changes are correctly formatted and that all links are functional.

Accuracy: Ensure content accurately reflects the implementation and technical behavior.
Self-review: Re-read changes for formatting, correctness, and flow.
Link check: Verify all new and existing links leading to or from modified pages.