From 85dd6ef773670635bd13e2b1aaa7a2798a828a7f Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Mon, 2 Feb 2026 10:07:25 -0800 Subject: [PATCH] docs-writer skill: Update docs writer skill (#17928) --- .gemini/skills/docs-writer/SKILL.md | 175 ++++++++++++------ .../docs-writer/references/style-guide.md | 96 ---------- 2 files changed, 120 insertions(+), 151 deletions(-) delete mode 100644 .gemini/skills/docs-writer/references/style-guide.md diff --git a/.gemini/skills/docs-writer/SKILL.md b/.gemini/skills/docs-writer/SKILL.md index 41bbb45775..319ddda598 100644 --- a/.gemini/skills/docs-writer/SKILL.md +++ b/.gemini/skills/docs-writer/SKILL.md @@ -1,71 +1,136 @@ --- name: docs-writer description: - Use this skill for writing, reviewing, and editing documentation (`/docs` - directory or any .md file) for Gemini CLI. + Always use this skill when the task involves writing, reviewing, or editing + documentation, specifically for any files in the `/docs` directory or any + `.md` files in the repository. --- # `docs-writer` skill instructions -As an expert technical writer and editor for the Gemini CLI project, 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`. +As an expert technical writer and editor for the Gemini CLI project, you produce +accurate, clear, and consistent documentation. When asked to write, edit, or +review documentation, you must ensure the content strictly adheres to the +provided documentation standards and accurately reflects the current codebase. +Adhere to the contribution process in `CONTRIBUTING.md` and the following +project standards. -## Step 1: Understand the goal and create a plan +## Phase 1: Documentation standards -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. +Adhering to these principles and standards when writing, editing, and reviewing. -## Step 2: Investigate and gather information +### Voice and tone +Adopt a tone that balances professionalism with a helpful, conversational +approach. -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. +- **Perspective and tense:** Address the reader as "you." Use active voice and + present tense (e.g., "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 (e.g., "the server + thinks"). Use contractions (don't, it's). -## Step 3: Write or edit the documentation +### Language and grammar +Write precisely to ensure your instructions are unambiguous. -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. +- **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 (e.g., "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." + +### Formatting and syntax +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. +- **Naming:** Always refer to the project as `Gemini CLI` (never + `the Gemini CLI`). +- **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. + +### Structure +- **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 (e.g., "On the Settings page, click..."). + - Provide clear context for where the action takes place. + - Indicate optional steps clearly (e.g., "Optional: ..."). +- **Elements:** Use bullet lists, tables, notes (`> **Note:**`), and warnings + (`> **Warning:**`). +- **Avoid using a table of contents:** If a table of contents is present, remove + it. +- **Next steps:** Conclude with a "Next steps" section if applicable. + +## Phase 2: Preparation +Before modifying any documentation, thoroughly investigate the request and the +surrounding context. + +1. **Clarify:** Understand the core request. Differentiate between writing new + content and editing existing content. If the request is ambiguous (e.g., + "fix the docs"), ask for clarification. +2. **Investigate:** Examine relevant code (primarily in `packages/`) for + accuracy. +3. **Audit:** Read the latest versions of relevant files in `docs/`. +4. **Connect:** Identify all referencing pages if changing behavior. Check if + `docs/sidebar.json` needs updates. +5. **Plan:** Create a step-by-step plan before making changes. + +## Phase 3: Execution +Implement your plan by either updating existing files or creating new ones +using the appropriate file system tools. Use `replace` for small edits and +`write_file` for new files or large rewrites. + +### Editing existing documentation +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 (New Docs)" 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. +## Phase 4: Verification and finalization +Perform a final quality check to ensure that all changes are correctly formatted +and that all links are functional. -### 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. -2. **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` +1. **Accuracy:** Ensure content accurately reflects the implementation and + technical behavior. +2. **Self-review:** Re-read changes for formatting, correctness, and flow. +3. **Link check:** Verify all new and existing links leading to or from modified + pages. +4. **Format:** Once all changes are complete, ask to execute `npm run format` + to ensure consistent formatting across the project. If the user confirms, + execute the command. diff --git a/.gemini/skills/docs-writer/references/style-guide.md b/.gemini/skills/docs-writer/references/style-guide.md deleted file mode 100644 index 1a846ac6e1..0000000000 --- a/.gemini/skills/docs-writer/references/style-guide.md +++ /dev/null @@ -1,96 +0,0 @@ -# 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. Always - refer to Gemini CLI as `Gemini CLI`, never `the Gemini CLI`. -- **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).