Skip to content

Add agent instructions for aligning with Google style guide #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nscuro wants to merge 2 commits into
base: main
Choose a base branch
from
+18 −0
Open

Add agent instructions for aligning with Google style guide #91

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b11ba79
Add agent instructions for aligning with Google style guide
nscuro May 20, 2026
473996e
Potential fix for pull request finding
nscuro May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,13 +60,31 @@ Some reference pages are generated from source repositories. Do not edit these f
- **Protobuf schemas** (`docs/reference/schemas/{notification,policy}.md`): generated by `protoc-gen-doc` from proto definitions in the API server repo. Regenerate with `make generate-proto-docs APISERVER_DIR=<path>`.
- **OpenAPI specs** (`docs/reference/api/openapi-*.yaml`): downloaded from API server CI artifacts via the `update-openapi-docs` workflow.

## Language and style

Follow the [Google developer documentation style guide](https://developers.google.com/style). Vale enforces the machine-checkable subset (Oxford commas, contractions, em-dashes, semicolons, slang, sentence-case headings, date formats, passive voice, banned words). Apply the rest by hand:

- Short sentences, active voice, common words. Domain terms (CEL, SBOM, outbox) are fine where they carry weight.
- No idioms, metaphors, or cultural references — readers translate these docs with machine tools.
- American English spellings (color, organize, behavior, summarize, centralized, normalize).
- Address the reader as "you", never "the user".
- No filler or condescension: "simply", "just", "easy", "obvious", "merely", "basically", "please".
- No positional references ("above", "below", "earlier"). Link to the section by name instead.
- Descriptive link text. Never "click here", "here", or "this page".
- "Select" for UI actions, not "click". Bold for UI labels. Backticks for code, commands, paths, env vars, and identifiers.
- Abbreviations in `docs/includes/abbreviations.md` need no first-use expansion (MkDocs renders a hover tooltip). Spell out others on first use per page, and add the abbreviation to that file if it spans more than one page.
- Numbers zero–nine spelled out, 10+ as numerals. Always numerals for versions, ports, durations, and units.

Where Google style conflicts with `context/diataxis-contract.md`, Diataxis wins. Notably: Tutorials use "we" (tutor-learner partnership) and "will" to set expectations; Guides, Concepts, and Reference use "you" or no pronoun.

## Writing conventions

- Do not modify files in `existing-docs/`.
- Do not add files to `source/` without instruction.
- Use ATX-style headings (`# Heading`), not setext.
- Inline HTML is allowed (admonitions, tabs).
- No line length limit for Markdown prose.
- End linted Markdown files in `docs/` and `context/` with a single trailing newline (markdownlint MD047).
- YAML indentation: 2 spaces, no document-start markers.
- Vale enforces Google developer style and write-good rules. Accepted/rejected terms are in `.vale/styles/config/vocabularies/DependencyTrack/`.
- Page-specific images mirror the docs tree under `docs/assets/images/`: an image used by `docs/<section>/<page>.md` lives at `docs/assets/images/<section>/<page>/<name>.<ext>`. Shared assets (e.g. `logo.svg`) stay at the root of `docs/assets/images/`.