Docs Writer

docs-writer skill instructions

As an expert technical writer and editor, your goal is to produce and refine documentation that is accurate, clear, consistent, and easy for users to understand. You must adhere to the documentation contribution process outlined in CONTRIBUTING.md.

Step 1: Understand the goal and create a plan

1. Clarify the request: Fully understand the user's documentation request. Identify the core feature, command, or concept that needs work. 2. Differentiate the task: Determine if the request is primarily for writing new content or editing existing content. If the request is ambiguous (e.g., "fix the docs"), ask the user for clarification. 3. Formulate a plan: Create a clear, step-by-step plan for the required changes.

Step 2: Investigate and gather information

1. Read the code: Thoroughly examine the relevant codebase, primarily within the packages/ directory, to ensure your work is backed by the implementation and to identify any gaps. 2. Identify files: Locate the specific documentation files in the docs/ directory that need to be modified. Always read the latest version of a file before you begin work. 3. Check for connections: Consider related documentation. If you change a command's behavior, check for other pages that reference it. If you add a new page, check if docs/sidebar.json needs to be updated. Make sure all links are up to date.

Step 3: Write or edit the documentation

1. Follow the style guide: Adhere to the rules in references/style-guide.md. Read this file to understand the project's documentation standards. 2. Ensure the new documentation accurately reflects the features in the code. 3. Use `replace` and `write_file`: Use file system tools to apply your planned changes. For small edits, replace is preferred. For new files or large rewrites, write_file is more appropriate.

Sub-step: Editing existing documentation (as clarified in Step 1)

• Gaps: Identify areas where the documentation is incomplete or no longer reflects existing code.
• Tone: Ensure the tone is active and engaging, not passive.
• 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.

Step 4: Verify and finalize

1. Review your work: After making changes, re-read the files to ensure the documentation is well-formatted, and the content is correct based on existing code. 2. Link verification: Verify the validity of all links in the new content. Verify the validity of existing links leading to the page with the new content or deleted content. 3. Offer to run npm format: Once all changes are complete, offer to run the project's formatting script to ensure consistency by proposing the command: npm run format

Documentation style guide

I. Core principles

1. Clarity: Write for easy understanding. Prioritize clear, direct, and simple language. 2. Consistency: Use consistent terminology, formatting, and style throughout the documentation. 3. Accuracy: Ensure all information is technically correct and up-to-date. 4. Accessibility: Design documentation to be usable by everyone. Focus on semantic structure, clear link text, and image alternatives. 5. Global audience: Write in standard US English. Avoid slang, idioms, and cultural references. 6. Prescriptive: Guide the reader by recommending specific actions and paths, especially for complex tasks.

II. Voice and tone

• Professional yet friendly: Maintain a helpful, knowledgeable, and conversational tone without being frivolous.
• Direct: Get straight to the point. Keep paragraphs short and focused.
• Second person: Address the reader as "you."
• Present tense: Use the present tense to describe functionality (e.g., "The API returns a JSON object.").
• Avoid: Jargon, slang, marketing hype, and overly casual language.

III. Language and grammar

• Active voice: Prefer active voice over passive voice.
• _Example:_ "The system sends a notification." (Not: "A notification is sent by the system.")
• Contractions: Use common contractions (e.g., "don't," "it's") to maintain a natural tone.
• Simple vocabulary: Use common words. Define technical terms when necessary.
• Conciseness: Keep sentences short and focused, but don't omit helpful information.
• "Please": Avoid using the word "please."

IV. Procedures and steps

• Start each step with an imperative verb (e.g., "Connect to the database").
• Number steps sequentially.
• Introduce lists of steps with a complete sentence.
• Put conditions before instructions, not after.
• Provide clear context for where the action takes place (e.g., "In the administration console...").
• Indicate optional steps clearly (e.g., "Optional: ...").

V. Formatting and punctuation

• Text wrap: Wrap all text at 80 characters, with exceptions for long links or tables.
• Headings, titles, and bold text: Use sentence case. Structure headings hierarchically.
• Lists: Use numbered lists for sequential steps and bulleted lists for all other lists. Keep list items parallel in structure.
• Serial comma: Use the serial comma (e.g., "one, two, and three").
• Punctuation: Use standard American punctuation. Place periods inside quotation marks.
• Dates: Use unambiguous date formatting (e.g., "January 22, 2026").

VI. UI, code, and links

• UI elements: Put UI elements in bold. Focus on the task when discussing interaction.
• Code: Use code font for filenames, code snippets, commands, and API elements. Use code blocks for multi-line samples.
• Links: Use descriptive link text that indicates what the link leads to. Avoid "click here."

VII. Word choice and terminology

• Consistent naming: Use product and feature names consistently.
• Specific verbs: Use precise verbs.
• Avoid:
• Latin abbreviations (e.g., use "for example" instead of "e.g.").
• Placeholder names like "foo" and "bar" in examples; use meaningful names instead.
• Anthropomorphism (e.g., "The server thinks...").
• "Should": Be clear about requirements ("must") vs. recommendations ("we recommend").

VIII. Files and media

• Filenames: Use lowercase letters, separate words with hyphens (-), and use standard ASCII characters.
• Images: Provide descriptive alt text for all images. Provide high-resolution or vector images when practical.

IX. Accessibility quick check

• Provide descriptive alt text for images.
• Ensure link text makes sense out of context.
• Use semantic HTML elements correctly (headings, lists, tables).