Documentation and writing style
Purpose
Keep NVCF documentation plain, consistent, and useful for external readers.
Write short docs an agent or contributor can act on without private context.
Avoid typographic Unicode that breaks grep and diff tools, and avoid emphasis
patterns that make docs noisy.
When to use
- Any new or edited public Markdown in this repo.
AGENTS.md, CLAUDE.md, SKILL.md, READMEs, plans, and guides.- GitHub issue bodies, commit messages, and Pull Request descriptions.
- Existing docs you are changing for another reason.
Instructions
-
No markdown bold for emphasis. Do not use **...**, __...__, raw HTML
<b>, or <strong>. Use headings, lists, and backticks for paths, commands,
env vars, and identifiers.
-
No emojis in documentation or user-facing prose.
-
No em-dash (Unicode U+2014) or en-dash (U+2013). Split the thought into two
sentences, or use a comma, semicolon, parenthesis, or colon.
-
ASCII only in committed prose. Avoid smart quotes, ellipsis characters,
non-breaking spaces, arrows, and other typographic Unicode. Prefer -> over an
arrow glyph and ... over a single-character ellipsis. Code blocks and quoted
fixtures are exempt.
-
Be succinct. Prefer short sentences and direct wording. Cut filler and
repetition. Keep one idea per sentence when possible.
-
Prefer lists for short, scan-friendly structure. Use bullets for unordered
items and numbered lists when sequence, priority, or stable rule references
matter. Use tables only when columns make comparison, status, option tradeoffs,
or matrix decisions easier. Do not turn a short list into a table.
-
Be easy to understand. Define acronyms on first use if the audience is broad.
Prefer concrete examples over abstract jargon.
-
Write for GitHub readers. Use public names, public paths, and public
behavior. Replace private evidence with the user-visible reason for the change.
-
Keep agent guidance actionable. Say when to use a skill, what to inspect
first, what command to run, and what done means. Do not add temporary branch
status, Pull Request queues, merge-order notes, or private routing details.
-
Avoid vague agent language. Remove filler such as "ensure", "leverage",
"robust", "comprehensive", "where applicable", and "as needed" unless the term
adds a concrete condition.
Examples
Inline bold label, replaced with a plain prefix:
Before: **Note:** restart after edit.
After: Note: restart after edit.
Bold section header, replaced with a real heading:
Before: **Prerequisites**
- Repository access to github.com/NVIDIA/nvcf.
After: ## Prerequisites
- Repository access to github.com/NVIDIA/nvcf.
Double hyphen used as a dash, replaced with a period:
Before: Services live upstream -- this repo mirrors them.
After: Services live upstream. This repo mirrors them.
Long agent guidance, replaced with commands and durable criteria:
Before: Ensure agents comprehensively verify symlink fanout where applicable.
After: Run `python3 ai-tooling/dev/hooks/validate-skill-fanout.py` after
changing root skills. Fix every reported path before finishing.
Editing existing files
If a file already uses bold, emojis, em-dashes, en-dashes, or non-ASCII
punctuation, normalize it when you touch that file for another reason, or when
the user asks for a style pass. Do not expand scope into unrelated trees just to
fix style.
Limitations
- The rules target agent-edited prose in this repo. Upstream documentation
keeps its own style until merged natively.
- There is no automated linter for prose today. Review catches style issues.
Exceptions
- Content you are quoting verbatim, such as upstream LICENSE text, cited errors,
or user paste.
- Generated files where the generator controls formatting. Fix style in the
generator if needed.
- Auto-generated changelogs or release notes assembled from external commit
messages. Fix the source commits, not the rolled-up file.
