From c0d52403b3d730248a9311f1bbcee731201f2cf9 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Thu, 29 Jan 2026 17:46:40 -0800 Subject: [PATCH] Docs-writer skill: Update language and style guide information. --- .gemini/skills/docs-writer/SKILL.md | 24 ++++- .../docs-writer/references/style-guide.md | 96 ------------------- 2 files changed, 19 insertions(+), 101 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 56dc0fa140..1ef06094c3 100644 --- a/.gemini/skills/docs-writer/SKILL.md +++ b/.gemini/skills/docs-writer/SKILL.md @@ -24,7 +24,9 @@ approach. - **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. +- **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 @@ -55,10 +57,13 @@ accessible. `the Gemini CLI`). - **Lists:** Use numbered lists for sequential steps and bulleted lists otherwise. Keep list items parallel in structure. -- **UI & Code:** Use **bold** for UI elements and `code font` for filenames, - snippets, commands, and API elements. +- **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. @@ -91,6 +96,8 @@ project's quality standards. #### Editing 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. @@ -99,8 +106,12 @@ project's quality standards. #### Structure (New Docs) - **BLUF:** Start with an introduction explaining what to expect. +- **Experimental features:** If a feature is experimental, add the following + note immediately after the introductory paragraph: + `> **Note:** This feature is in preview and may be 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..."). @@ -111,7 +122,8 @@ project's quality standards. - **Next steps:** Conclude with a "Next steps" section if applicable. #### Verification -- Ensure content accurately reflects the implementation. +- **Accuracy:** Ensure content accurately reflects the implementation and + technical behavior. ## Phase 4: Verification and finalization Perform a final quality check to ensure that all changes are correctly formatted @@ -120,4 +132,6 @@ and that all links are functional. 1. **Self-review:** Re-read changes for formatting, correctness, and flow. 2. **Link Check:** Verify all new and existing links leading to or from modified pages. -3. **Format:** Propose `npm run format` after completing all changes. +3. **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).