MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-04-15 07:41:03 -07:00
Code Issues Packages Projects Releases Wiki Activity

Automated documentation audit (#24567)

Browse Source
This commit is contained in:
Sam Roberts
2026-04-09 11:45:24 -07:00
committed by GitHub
parent a9b5c693ca
commit f387e456be
4 changed files with 266 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gemini/skills/docs-changelog/SKILL.md
View File

@@ -162,5 +162,7 @@ instructions for the other section.
## Finalize
- After making changes, run `npm run format` ONLY to ensure consistency.
- After making changes, if `npm run format` fails, it may be necessary to run
`npm install` first to ensure all formatting dependencies are available.
Then, run `npm run format` to ensure consistency.
- Delete any temporary files created during the process.

33
.gemini/skills/docs-writer/SKILL.md
View File

@@ -1,7 +1,7 @@
---
name: docs-writer
description:
Always use this skill when the task involves writing, reviewing, or editing
Always use this skill when the task involves writing, reviewing, or editing
files in the `/docs` directory or any `.md` files in the repository.
---
@@ -24,7 +24,7 @@ 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.
- **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.
@@ -47,8 +47,8 @@ Write precisely to ensure your instructions are unambiguous.
"foo" or "bar."
- **Quota and limit terminology:** For any content involving resource capacity
or using the word "quota" or "limit", strictly adhere to the guidelines in
the `quota-limit-style-guide.md` resource file. Generally, Use "quota" for the
administrative bucket and "limit" for the numerical ceiling.
the `quota-limit-style-guide.md` resource file. Generally, Use "quota" for
the administrative bucket and "limit" for the numerical ceiling.
### Formatting and syntax
Apply consistent formatting to make documentation visually organized and
@@ -120,7 +120,7 @@ accessible.
> This is an experimental feature currently under active development.
- **Headings:** Use hierarchical headings to support the user journey.
- **Procedures:**
- **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.
@@ -134,7 +134,7 @@ accessible.
## Phase 2: Preparation
Before modifying any documentation, thoroughly investigate the request and the
surrounding context.
surrounding context.
1. **Clarify:** Understand the core request. Differentiate between writing new
content and editing existing content. If the request is ambiguous (e.g.,
@@ -145,6 +145,8 @@ surrounding context.
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.
6. **Audit Docset:** If asked to audit the documentation, follow the procedural
guide in [docs-auditing.md](./references/docs-auditing.md).
## Phase 3: Execution
Implement your plan by either updating existing files or creating new ones
@@ -157,7 +159,7 @@ 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
- **Structure:** Apply "Structure (New Docs)" rules (BLUF, headings, etc.) when
adding new sections to existing pages.
- **Headers**: If you change a header, you must check for links that lead to
that header and update them.
@@ -168,15 +170,16 @@ documentation.
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.
Perform a final quality check to ensure that all changes are correctly
formatted and that all links are functional.
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. If you changed a header, ensure that any links that lead to it are
updated.
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.
3. **Link check:** Verify all new and existing links leading to or from
modified pages. If you changed a header, ensure that any links that lead to
it are updated.
4. **Format:** If `npm run format` fails, it may be necessary to run `npm
install` first to ensure all formatting dependencies are available. 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.

195
.gemini/skills/docs-writer/references/docs-auditing.md Normal file
View File

@@ -0,0 +1,195 @@
# 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.

50
.github/workflows/docs-audit.yml vendored Normal file
View File

@@ -0,0 +1,50 @@
name: 'Weekly Docs Audit'
on:
schedule:
# Runs every Monday at 00:00 UTC
- cron: '0 0 * * MON'
workflow_dispatch:
jobs:
audit-docs:
runs-on: 'ubuntu-latest'
permissions:
contents: 'write'
pull-requests: 'write'
steps:
- name: 'Checkout repository'
uses: 'actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5'
with:
fetch-depth: 0
ref: 'main'
- name: 'Set up Node.js'
uses: 'actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020'
with:
node-version: '20'
- name: 'Run Docs Audit with Gemini'
uses: 'google-github-actions/run-gemini-cli@a3bf79042542528e91937b3a3a6fbc4967ee3c31'
with:
gemini_api_key: '${{ secrets.GEMINI_API_KEY }}'
prompt: |
Activate the 'docs-writer' skill.
**Task:** Execute the docs audit procedure, as defined in your 'docs-auditing.md' reference.
- name: 'Create Pull Request with Audit Results'
uses: 'peter-evans/create-pull-request@c5a7806660adbe173f04e3e038b0ccdcd758773c'
with:
token: '${{ secrets.GEMINI_CLI_ROBOT_GITHUB_PAT }}'
commit-message: 'docs: weekly audit results for ${{ github.run_id }}'
title: 'Docs Audit for Week of ${{ github.event.schedule }}'
body: |
This PR contains the auto-generated documentation audit for the week. It includes a new `audit-results-*.md` file with findings and any direct fixes applied by the agent.
Please review the suggestions and merge.
branch: 'docs-audit-${{ github.run_id }}'
base: 'main'
team-reviewers: 'gemini-cli-docs, gemini-cli-maintainers'
delete-branch: true