docs: add a documentation style guide for consistent docs#3697
Conversation
|
@coderabbitai full_review, thanks! |
Summary by CodeRabbit
WalkthroughThe pull request adds ChangesDocumentation style guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
✅ Action performedFull review finished. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@DOCS_STYLE_GUIDE.md`:
- Line 371: Update the checklist item in DOCS_STYLE_GUIDE.md to remove the
Latinism examples and rephrase it as “Avoid Latinisms and vivid idioms.”
- Line 1: Update the DOCS_STYLE_GUIDE.md H1 heading to title case, changing “How
to write documentation in infra-controller” to “How to Write Documentation in
infra-controller”; leave the remaining guide content unchanged.
- Around line 107-112: Update the acronym guidance in DOCS_STYLE_GUIDE.md so
each first-use term includes its full expansion followed by the abbreviation,
replacing the abbreviation-only entries for LLM, RAG, SLM, VLM, and MoE.
Preserve the exceptions for common terms and the existing plural-acronym rule.
- Around line 59-61: Add complete sentence lead-ins ending with colons
immediately before the Accessibility Language and Latinisms tables, matching the
guide’s table-formatting rule. Ensure the lead-ins clearly introduce each table
and preserve the existing headings, columns, and content.
In `@STYLE_GUIDE.md`:
- Around line 8-10: Update the cross-reference wording in the documentation
notice to use “refer to” instead of “see,” while preserving the existing
DOCS_STYLE_GUIDE.md link and surrounding text.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 58c1a0ab-dcda-4ef3-a42f-729dd9072484
📒 Files selected for processing (4)
AGENTS.mdCONTRIBUTING.mdDOCS_STYLE_GUIDE.mdSTYLE_GUIDE.md
| - [ ] NVIDIA spelled correctly in all caps; "an NVIDIA". | ||
| - [ ] Active voice, present tense, second person ("you"). | ||
| - [ ] No contractions. | ||
| - [ ] No Latinisms (e.g., etc., i.e., via) and no vivid idioms (spin up, footgun). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the forbidden Latinisms from the checklist.
The checklist says “No Latinisms” while using e.g. and etc. in the same bullet. Rephrase it as “Avoid Latinisms and vivid idioms.”
As per path instructions, Markdown must be reviewed for correctness, clarity, spelling, grammar, working links, and realistic, safe examples.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@DOCS_STYLE_GUIDE.md` at line 371, Update the checklist item in
DOCS_STYLE_GUIDE.md to remove the Latinism examples and rephrase it as “Avoid
Latinisms and vivid idioms.”
Source: Path instructions
There was a problem hiding this comment.
🧹 Nitpick comments (1)
DOCS_STYLE_GUIDE.md (1)
288-290: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse parallel definitions for list types.
This semicolon-separated sentence is dense and conflicts with the guide’s preference for splitting complex prose into sentences or lists. Rewrite the three types as parallel definitions.
Proposed revision
-- Types: **Bulleted** (order does not matter, lead-in with a colon); - **Numbered** (sequential steps); **Definition** (bold term, indented - definition). +- **Bulleted:** Use when order does not matter. +- **Numbered:** Use for sequential steps. +- **Definition:** Use a bold term followed by an indented definition.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@DOCS_STYLE_GUIDE.md` around lines 288 - 290, Rewrite the list-types guidance in DOCS_STYLE_GUIDE.md as three parallel definition entries for Types, Bulleted, Numbered, and Definition, using consistent formatting and separate lines instead of the current semicolon-separated sentence.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@DOCS_STYLE_GUIDE.md`:
- Around line 288-290: Rewrite the list-types guidance in DOCS_STYLE_GUIDE.md as
three parallel definition entries for Types, Bulleted, Numbered, and Definition,
using consistent formatting and separate lines instead of the current
semicolon-separated sentence.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 54361333-9fac-467a-aadb-639c0b777b16
📒 Files selected for processing (4)
AGENTS.mdCONTRIBUTING.mdDOCS_STYLE_GUIDE.mdSTYLE_GUIDE.md
|
@coderabbitai full_review, thanks! |
|
🐇 ✅ Action performedFull review finished. |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@DOCS_STYLE_GUIDE.md`:
- Around line 140-141: Update the currency-formatting example in the style guide
so the currency code “USD” is preceded by a numeric amount, using a complete
example such as “1,000 USD”; preserve the surrounding formatting guidance.
- Around line 84-85: Correct the exception sentence in the style guide by
replacing the incorrect “may also except” wording with a direct grammatical
instruction stating that formal or academic content and space-constrained
contexts may omit italics.
- Around line 89-93: Update the prose immediately preceding the “Avoid / Use
Instead” table in DOCS_STYLE_GUIDE.md so its complete introductory sentence ends
with a colon rather than a period, preserving the table content and surrounding
guidance.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 3f88806a-0843-4e5e-96c5-022510fafc20
📒 Files selected for processing (4)
AGENTS.mdCONTRIBUTING.mdDOCS_STYLE_GUIDE.mdSTYLE_GUIDE.md
|
@coderabbitai full_review, thanks! |
|
🐇 ✅ Action performedFull review finished. |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@DOCS_STYLE_GUIDE.md`:
- Line 250: Resolve the inconsistency in the user action formatting row of the
Markdown style guide by making the rule and example agree: either change the
label to “User input” or bold the full action consistently. Keep the table’s
guidance clear and unambiguous.
- Line 17: Update the sentence in DOCS_STYLE_GUIDE.md to replace “may” with
“can,” so it reads “Teams can layer their own conventions on top” and remains
consistent with the guide’s wording.
- Line 281: Update the “Trademarks” guidance in DOCS_STYLE_GUIDE.md to replace
the ambiguous “PR” abbreviation with either the expanded “public relations (PR)”
or the intended “pull-request content,” while preserving the existing
first-product-mention trademark requirement.
- Line 340: Clarify the contrast requirement in the accessibility guidance by
specifying whether the 4.5:1 minimum applies universally or only to normal-sized
text. If it is universal, state that explicitly; otherwise distinguish normal
text, large text, and non-text contrast criteria with their applicable
thresholds.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 02d7332e-cf66-4ac8-b157-f9d5edc7e380
📒 Files selected for processing (4)
AGENTS.mdCONTRIBUTING.mdDOCS_STYLE_GUIDE.mdSTYLE_GUIDE.md
🚧 Files skipped from review as they are similar to previous changes (3)
- STYLE_GUIDE.md
- AGENTS.md
- CONTRIBUTING.md
polarweasel
left a comment
polarweasel
left a comment
There was a problem hiding this comment.
Needs a re-think. Posting a copy of an internal guide for everyone's agents to consume won't fly. Point them to our internal resources (but then we're exposing internal URLs, hrmmm), or tell them to prompt the user install the skills. As a bonus, that shortens this up considerably.
| - Do not put a register mark (®) after "NVIDIA" when it refers to the company; | ||
| use trademark symbols only on product references. |
There was a problem hiding this comment.
We don't do the symbols at all in technical docs, really. Marketing is different, of course, but this is linked at the bottom of every docs page:
There was a problem hiding this comment.
This is too much. Our docs style guide is NOT public, and this is a complete repetition of what's already available to us within NVIDIA. I was thinking you were setting things up so people's agents would take advantage of the docs skills we provide!
We already produce style-consistent documentation, but the conventions lived only in our heads, so hand-authored docs drift in voice, formatting, and NVIDIA branding. This adds `DOCS_STYLE_GUIDE.md`, a loadable reference any contributor or agent can apply before writing docs, and wires it into the places authors actually look. Primary callouts are: - `DOCS_STYLE_GUIDE.md` at the repo root captures the prose and formatting conventions for user-facing docs (branding, PACE voice, word choice, numbers, punctuation, grammar, formatting, lists and tables, links, accessibility, and readability), plus an over-application-safeguards section and a quick checklist, aligned with NVIDIA's documentation style. - It lives at the root, deliberately outside `docs/`, so it stays an authoring reference and is not published as a page on the Fern docs site. - `AGENTS.md`, `STYLE_GUIDE.md`, and `CONTRIBUTING.md` now point to it, so agents and human contributors both find it. This supports NVIDIA#3684 Signed-off-by: Chet Nichols III <chetn@nvidia.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@DOCS_STYLE_GUIDE.md`:
- Around line 273-274: Update the GitHub repository example in the formatting
guidance so the /NVIDIA/NeMo path is rendered in Markdown inline code, while
preserving the surrounding wording and repository naming guidance.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 51b8c9b4-2f75-47c2-9d63-ff7665791e63
📒 Files selected for processing (4)
AGENTS.mdCONTRIBUTING.mdDOCS_STYLE_GUIDE.mdSTYLE_GUIDE.md
🚧 Files skipped from review as they are similar to previous changes (3)
- AGENTS.md
- CONTRIBUTING.md
- STYLE_GUIDE.md
| - GitHub repos: use a forward slash and the repo name ("the /NVIDIA/NeMo GitHub | ||
| repo"), not bare "the GitHub repo". |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Render the repository path in monospace.
The formatting table requires paths to use monospace, but this example leaves /NVIDIA/NeMo as prose. Format it as `/NVIDIA/NeMo` so the example follows the guide’s own rules.
As per path instructions, Markdown must be reviewed for correctness, clarity, spelling, grammar, working links, and realistic, safe examples.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@DOCS_STYLE_GUIDE.md` around lines 273 - 274, Update the GitHub repository
example in the formatting guidance so the /NVIDIA/NeMo path is rendered in
Markdown inline code, while preserving the surrounding wording and repository
naming guidance.
Source: Path instructions
2 participants
Adds
DOCS_STYLE_GUIDE.md, a repo-root reference for how we write documentation, so contributors and agents produce style-consistent, on-brand docs no matter who writes them. It covers branding, PACE voice, word choice, numbers, punctuation, grammar, formatting, lists and tables, links, accessibility, and readability, plus over-application safeguards and a quick checklist, aligned with NVIDIA's documentation style.docs/, so it stays an authoring reference and is not published as a page on the Fern docs site.AGENTS.md,STYLE_GUIDE.md, andCONTRIBUTING.mdnow point to it, so agents and human contributors both find it.This supports #3684