gemini-cli/.gemini/skills/docs-writer/references/docs-auditing.md

Procedural Guide: Auditing the Docset

This guide outlines the process for auditing the Gemini CLI documentation for correctness and adherence to style guidelines. This process involves both an "Editor" and "Technical Writer" phase.

Objective

To ensure all public-facing documentation is accurate, up-to-date, adheres to the Gemini CLI documentation style guide, and reflects the current state of the codebase.

Phase 1: Editor Audit

Role: The editor is responsible for identifying potential issues based on style guide violations and technical inaccuracies.

Steps

1. Identify Documentation Scope:

   • Read docs/sidebar.json to get a list of all viewable documentation pages.
   • For each entry with a slug, convert it into a file path (e.g., docs -> docs/index.md, docs/get-started -> docs/get-started.md). Ignore entries with link properties.

2. Prepare Audit Results File:

   • Create a new Markdown file named audit-results-[YYYY-MM-DD].md (e.g., audit-results-2026-03-13.md). This file will contain all identified violations and recommendations.

3. Retrieve Style Guidelines:

   • Familiarize yourself with the docs-writer skill instructions and the included style guidelines.

4. Audit Each Document:

   • For each documentation file identified in Step 1, read its content.
   • Review against Style Guide:
     • Voice and Tone Violations:
       • Unprofessional Tone: Identify phrasing that is overly casual, defensive, or lacks a professional and friendly demeanor.
       • Indirectness or Vagueness: Identify sentences that are unnecessarily wordy or fail to be concise and direct.
       • Incorrect Pronoun: Identify any use of third-person pronouns (e.g., "we," "they," "the user") when referring to the reader, instead of the second-person pronoun "you".
       • Passive Voice: Identify sentences written in the passive voice.
       • Incorrect Tense: Identify the use of past or future tense verbs, instead of the present tense.
       • Poor Vocabulary: Identify the use of jargon, slang, or overly informal language.
     • Language and Grammar Violations:
       • Lack of Conciseness: Identify unnecessarily long phrases or sentences.
       • Punctuation Errors: Identify incorrect or missing punctuation.
       • Ambiguous Dates: Identify dates that could be misinterpreted (e.g., "next Monday" instead of "April 15, 2026").
       • Abbreviation Usage: Identify the use of abbreviations that should be spelled out (e.g., "e.g." instead of "for example").
       • Terminology: Check for incorrect or inconsistent use of product-specific terms (e.g., "quota" vs. "limit").
     • Formatting and Syntax Violations:
       • Missing Overview: Check for the absence of a brief overview paragraph at the start of the document.
       • Line Length: Identify any lines of text that exceed 80 characters (text wrap violation).
       • Casing: Identify incorrect casing for headings, titles, or named entities (e.g., product names like Gemini CLI).
       • List Formatting: Identify incorrectly formatted lists (e.g., inconsistent indentation or numbering).
       • Incorrect Emphasis: Identify incorrect use of bold text (should only be used for UI elements) or code font (should be used for code, file names, or command-line input).
       • Link Quality: Identify links with non-descriptive anchor text (e.g., "click here").
       • Image Alt Text: Identify images with missing or poor-quality (non-descriptive) alt text.
     • Structure Violations:
       • Missing BLUF: Check for the absence of a "Bottom Line Up Front" summary at the start of complex sections or documents.
       • Experimental Feature Notes: Identify experimental features that are not clearly labeled with a standard note.
       • Heading Hierarchy: Check for skipped heading levels (e.g., going from ## to ####).
       • Procedure Clarity: Check for procedural steps that do not start with an imperative verb or where a condition is placed after the instruction.
       • Element Misuse: Identify the incorrect or inappropriate use of special elements (e.g., Notes, Warnings, Cautions).
       • Table of Contents: Identify the presence of a dynamically generated or manually included table of contents.
       • Missing Next Steps: Check for procedural documents that lack a "Next steps" section (if applicable).
   • Verify Code Accuracy (if applicable):
     • If the document contains code snippets (e.g., shell commands, API calls, file paths, Docker image versions), use grep_search and read_file within the packages/ directory (or other relevant parts of the codebase) to ensure the code is still accurate and up-to-date. Pay close attention to version numbers, package names, and command syntax.
   • Record Findings: For each violation or inaccuracy found:
     • Note the file path.
     • Describe the violation (e.g., "Violation (Language and Grammar): Uses 'e.g.'").
     • Provide a clear and actionable recommendation to correct the issue. (e.g., "Recommendation: Replace 'e.g.' with 'for example'." or "Recommendation: Replace '...' with '...' in active voice.).
     • Append these findings to audit-results-[YYYY-MM-DD].md.

Phase 2: Software Engineer Audit

Role: The software engineer is responsible for finding undocumented features by auditing the codebase and recent changelogs, and passing these findings to the technical writer.

Steps

1. Proactive Codebase Audit:

   • Audit high-signal areas of the codebase to identify undocumented features. You MUST review:
     • packages/cli/src/commands/
     • packages/core/src/tools/
     • packages/cli/src/config/settings.ts

2. Review Recent Updates:

   • Check recent changelogs in stable and announcements within the documentation to see if newly introduced features are documented properly.

3. Evaluate and Record Findings:

   • Determine if these features are adequately covered in the docs. They do not need to be documented word for word, but major features that customers should care about probably should have an article.
   • Append your findings to the audit-results-[YYYY-MM-DD].md file, providing a brief description of the feature and where it should be documented.

Phase 3: Technical Writer Implementation

Role: The technical writer handles input from both the editor and the software engineer, makes appropriate decisions about what to change, and implements the approved changes.

Steps

1. Review Audit Results:

   • Read audit-results-[YYYY-MM-DD].md to understand all identified issues, undocumented features, and recommendations from both the Editor and Software Engineer phases.

2. Make Decisions and Log Reasoning:

   • Create or update an implementation log (e.g., audit-implementation-log-[YYYY-MM-DD].md).
   • Make sure the logs are updated for all steps, documenting your reasoning for each recommendation (why it was accepted, modified, or rejected). This is required for a final check by a human in the PR.

3. Implement Changes:

   • For each approved recommendation:
     • Read the target documentation file.
     • Apply the recommended change using the replace tool. Pay close attention to old_string for exact matches, including whitespace and newlines. For multiple occurrences of the same simple string (e.g., "e.g."), use allow_multiple: true.
     • String replacement safeguards: When applying these fixes across the docset, you must verify the following:
       • Preserve Code Blocks: Explicitly verify that no code blocks, inline code snippets, terminal commands, or file paths have been erroneously capitalized or modified.
       • Preserve Literal Strings: Never alter the wording of literal error messages, UI quotes, or system logs. For example, if a style rule says to remove the word "please", you must NOT remove it if it appears inside a quoted error message (e.g., Error: Please contact your administrator).
       • Verify Sentence Casing: When removing filler words (like "please") from the beginning of a sentence or list item, always verify that the new first word of the sentence is properly capitalized.
     • For structural changes (e.g., adding an overview paragraph), use replace or write_file as appropriate.
     • For broken links, determine the correct new path or update the link text.
     • For creating new files (e.g., docs/get-started.md to fix a broken link, or a new feature article), use write_file.

4. Execute Auto-Generation Scripts:

   • Some documentation pages are auto-generated from the codebase and should be updated using npm scripts rather than manual edits. After implementing manual changes (especially if you edited settings or configurations based on SWE recommendations), ensure you run:
     • npm run docs:settings to generate/update the configuration reference.
     • npm run docs:keybindings to generate/update the keybindings reference.

5. Format Code:

   • Dependencies: If npm run format fails, it may be necessary to run npm install first to ensure all formatting dependencies are available.
   • After all changes have been implemented, run npm run format to ensure consistent formatting across the project.