astro-docs/STYLE_GUIDE.md
This document defines the standards for Nx documentation on nx.dev, including voice, grammar, formatting, and terminology.
For automated enforcement, see the Vale configuration section below.
When creating or reorganizing documentation, follow these five principles to determine where content belongs.
Don't overwhelm the user. Reveal complexity only as they advance in their journey.
The test: Is this for the first 30 minutes (Getting Started), the first 30 days (Features), or forever (Reference)?
Items in a list must be of the same "type" (noun, verb, or concept) to reduce cognitive load.
The test: Does this list mix concepts (mental model), tasks (update Nx), and products (React)? If yes, split it.
Separate learning (narrative/guides) from looking up (reference/API).
The test: Is the user here to learn a workflow (guide) or look up a flag syntax (reference)?
Distinguish architecture from features to keep "core concepts" pure.
The test: Can I explain this using only a pen and paper?
Distinguish platform features from ecosystem tools to prevent "Features" from becoming a junk drawer.
The test: Does this feature apply to every user (e.g., caching, Nx Agents)?
The sidebar has four top-level sections that follow the user journey:
Nx documentation is direct, practical, and confident. We write like a knowledgeable colleague pairing with you — not like a textbook, not like a marketing page, and not like a chatbot.
The voice should be:
| Do | Don't |
|---|---|
| "You can speed up builds by enabling remote caching." | "Nx allows you to speed up builds." |
"Run nx build to build your project." | "In order to build your project, you can run the nx build command." |
| "This works best with fewer than 50 projects." | "This feature can easily scale to any number of projects." |
"Nx reads your vite.config.ts and infers build targets automatically." | "Nx provides a robust and comprehensive mechanism for inferring build targets." |
"If the cache is stale, delete .nx/cache and retry." | "Should you encounter issues with caching, you may want to consider clearing your cache directory." |
Documentation must not read like it was generated by an AI assistant. Even when AI tools are used in the writing process, the output must be edited to sound like a human wrote it.
Never use these phrases:
Avoid hedging words unless genuinely needed:
Watch for AI-style sentence patterns:
Don't write about the document itself.
Do:
Don't:
Get right to the point. The reader already knows they're on a page — they want the information.
Don't use filler words that undermine the reader's trust.
Focus on what the reader can do, not what Nx does.
Do:
nx affected to run tasks only for projects impacted by your changes."Don't:
Words like "allow" and "enable" are signals you're writing from the product's perspective instead of the reader's.
Write in US English.
Use active voice in most cases.
Do: "Nx caches the build output." Don't: "The build output is cached by Nx."
Exception: When "Nx" as the subject sounds awkward, passive voice is fine. "The output is stored in .nx/cache" is better than "Nx stores the output in .nx/cache" if Nx isn't the focus of the sentence.
Use contractions. They make the text feel natural.
Don't contract for emphasis in warnings or error descriptions:
nx.json file."Don't contract proper nouns: "the Vite plugin is..." not "Vite's a plugin..."
Use sentence case for headings. Capitalize proper nouns only.
# Use remote caching to speed up CI## Configure the Vite pluginFeature names are lowercase unless they are a proper product name:
| Correct | Incorrect |
|---|---|
| remote caching | Remote Caching |
| project graph | Project Graph |
| Nx Cloud | nx cloud |
| Nx Console | nx console |
| Nx Agents | nx agents |
| Nx Replay | nx replay |
Spell out acronyms on first use per page. Don't spell out widely-known ones: CI, CD, API, URL, CLI, PR, IDE.
Don't make acronyms plural with apostrophes. Use APIs, not API's.
Spell out zero through nine. Use numerals for 10 and above. Always use numerals with units: "5 minutes", "3 projects."
Don't use possessives on product names. "the Docker CLI", not "Docker's CLI." "the Nx configuration", not "Nx's configuration."
## to ####).Use < and > for values the reader must replace:
nx run <project-name>:build
If the placeholder is inline, wrap it in a single backtick: <your-project>.
Use bold for:
Don't use bold for emphasis or keywords. If you need emphasis, rewrite the sentence to be clearer.
Use inline code (single backticks) for:
nx build, --parallelnx.json, .nx/cachetargetDefaults, namedInputstrue, false, successUse triple backticks with a language identifier:
```json
{
"targetDefaults": {
"build": {
"cache": true
}
}
}
```
plaintext if nothing else fits.{
// ... other config
"targetDefaults": {
"build": {
"cache": true
}
}
}
Links help readers find related information, but too many links make text hard to read.
Use descriptive text, not "here" or "this page."
Do:
Don't:
Standard patterns:
For more information, see [link text](url).To <do this thing>, see [link text](url).Minimize external links. They break over time and are hard to maintain. When you must link externally, prefer official documentation (e.g., Vite docs, Webpack docs) over blog posts or third-party guides.
-) for unordered lists.1. (Markdown auto-increments).Do:
You can clear the cache in the following ways:
- Delete the `.nx/cache` directory manually.
- Run `nx reset` to clear all cached results.
Don't:
You can clear the cache by:
- Deleting the `.nx/cache` directory manually.
- Running `nx reset`.
Use tables for structured data that benefits from a matrix layout. For simple lists of items with descriptions, use a regular list instead.
Use these terms consistently. When writing about Nx concepts, use the exact term from this list.
| Term | Usage notes |
|---|---|
| workspace | The root directory managed by Nx. Not "repo" or "monorepo" when referring to Nx's context. |
| project | An app or library within the workspace. |
| target | A task that can be run for a project (e.g., build, test, lint). |
| executor | The implementation behind a target. Not "builder." |
| generator | Code scaffolding tool. Not "schematic." |
| plugin | An Nx plugin that provides executors, generators, or graph inference. |
| task | A specific invocation of a target for a project (e.g., myapp:build). |
| project graph | The dependency graph between projects. |
| affected | Projects impacted by a code change. |
| cache / cached | Not "memoized" or "stored results." |
| remote caching | Sharing cached results across machines. Specific product: "Nx Replay." |
| Nx Cloud | The hosted CI/CD product. Always capitalized. |
| Nx Console | The IDE extension. Always capitalized. |
| Nx Agents | Distributed task execution product. Always capitalized. |
| Nx Replay | Remote caching product. Always capitalized. |
nx.json | Always in code style. |
project.json | Always in code style. |
Vale enforces many of the rules in this style guide automatically.
Configuration lives in astro-docs/:
.vale.ini — Main config. Scopes rules to src/content/docs/**/*.{mdoc,mdx,md}..vale/styles/Nx/ — Custom rules for Nx documentation.# Via Nx target (recommended)
nx vale astro-docs
# Directly (from astro-docs/ directory)
vale src/content/docs/
Vale is managed via mise. Run mise install from the repo root to install it.
You can also install directly via brew install vale (macOS) or apt-get install vale (Linux).
| Tier | Severity | Rules |
|---|---|---|
| 1 - Mechanical | error | Banned phrases, product capitalization |
| 2 - Structural | warning | Heading case, terminology, product possessives, self-referential writing, sentence patterns |
| 3 - Voice | suggestion | Trust-undermining words, marketing language, passive voice, serial commas |
Create a new .yml file in .vale/styles/Nx/.
Vale supports several extension points: existence, substitution, occurrence, repetition, consistency, conditional, capitalization, and metric.
Set level to match the tier: error for mechanical rules, warning for structural, suggestion for voice/judgment.