diff --git a/.gemini/skills/docs-writer/SKILL.md b/.gemini/skills/docs-writer/SKILL.md index 16502163c5..e2770d0bb8 100644 --- a/.gemini/skills/docs-writer/SKILL.md +++ b/.gemini/skills/docs-writer/SKILL.md @@ -1,63 +1,72 @@ + --- name: docs-writer description: - Use this skill when asked to write documentation (`/docs` directory) - for Gemini CLI. + Use this skill for writing, reviewing, and editing documentation (`/docs` + directory or any .md file) for Gemini CLI. --- # `docs-writer` skill instructions -As an expert technical writer for the Gemini CLI project, your goal is to -produce documentation that is accurate, clear, and consistent with the project's -standards. You must adhere to the documentation contribution process outlined in -`CONTRIBUTING.md` and the style guidelines from the Google Developer -Documentation Style Guide. +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`. ## 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 to be documented. -2. **Ask questions:** If the request is ambiguous or lacks detail, ask - clarifying questions. Don't invent or assume. It's better to ask than to - write incorrect documentation. + 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. If requested or necessary, store this plan in a temporary file or - a file identified by the user. + changes. ## Step 2: Investigate and gather information -1. **Read the code:** Thoroughly examine the relevant codebase, primarily within - the `packages/` directory, to ensure your writing is backed by the - implementation. +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 to edit it. -3. **Check for connections:** Consider related documentation. If you add a new - page, check if `docs/sidebar.json` needs to be updated. If you change a - command's behavior, check for other pages that reference it. Make sure links - in these pages are up to date. + 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: Draft the documentation +## Step 3: Write or edit the documentation -1. **Follow the style guide:** - - Text must be wrapped at 80 characters. Exceptions are long links or - tables, unless otherwise stated by the user. - - Use sentence case for headings, titles, and bolded text. - - Address the reader as "you". - - Use contractions to keep the tone more casual. - - Use simple, direct, and active language and the present tense. - - Keep paragraphs short and focused. - - Always refer to Gemini CLI as `Gemini CLI`, never `the Gemini CLI`. -2. **Use `replace` and `write_file`:** Use the file system tools to apply your - planned changes precisely. For small edits, `replace` is preferred. For new - files or large rewrites, `write_file` is more appropriate. +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, content is correct and based on existing - code, and that all new links are valid. -2. **Offer to run npm format:** Once all changes are complete and the user - confirms they have no more requests, offer to run the project's formatting - script to ensure consistency. Propose the following command: + 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` diff --git a/.gemini/skills/docs-writer/references/style-guide.md b/.gemini/skills/docs-writer/references/style-guide.md new file mode 100644 index 0000000000..c8eab11ae8 --- /dev/null +++ b/.gemini/skills/docs-writer/references/style-guide.md @@ -0,0 +1,95 @@ +# 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. +- **"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).