Documentation Style Guides

Inconsistent documentation is harder to read than inconsistent code, because the reader has no compiler to normalize it. When one page says "API key," another says "access token," and a third says "auth credential" — all referring to the same string — the reader has to work out whether these are three things or one. That cognitive tax compounds across a documentation set, and it's invisible to whoever wrote each individual page.

A style guide fixes it, and the important insight is that the terminology list matters more than the prose rules. Whether you write in second person or use the Oxford comma affects polish; whether the same concept has one name affects comprehension. Most of the value in this topic comes from a short list of "call it X, not Y" entries.

The second insight is that a style guide nobody enforces is a document nobody reads. Human reviewers don't reliably catch terminology drift or passive voice, and asking them to is a poor use of review attention. A prose linter in CI catches it mechanically, which turns the style guide from an aspiration into a property of the codebase.

TL;DR

Quick Example

A complete, enforceable setup:

The Vague.yml rule deserves note. "Simply run the migration" reads as friendly and lands as condescending when the reader is stuck — and the word adds nothing. Banning that small set of words measurably improves documentation tone with no judgment calls required.

Core Concepts

Adopt, then supplement

Writing a style guide from scratch is weeks of work producing something worse than what already exists. The established guides are comprehensive, well-reasoned, and free:

Pick one, then write a one-page supplement covering only what's specific to you: product terminology, code sample conventions, and the handful of places you deviate. That supplement is the part people will actually read.

The terminology list

Maintain this as a real artifact — a table in the style guide and a Vale rule so it's enforced. It's the single most valuable output of a style guide, and it also settles arguments: once "we call it the console" is written down, nobody relitigates it in review.

Include the entries where you're inconsistent, not the ones where you never make mistakes. The list should be short and specific to your actual failure modes.

Voice and tense

Present tense is the one people find unnatural and it's correct: documentation describes how the software behaves, and "will return" implies a future that hasn't happened. Active voice matters most because passive constructions hide the actor — "the request is validated" doesn't tell you whether the client, the gateway, or the service does it.

Structural conventions

Descriptive link text is an accessibility requirement as well as a style one — screen reader users often navigate by pulling up a list of links, and a page of "here" and "read more" is unusable.

Inclusive language

Two practical notes. Some of these have technical names fixed by an external API (master on a Git branch you don't control, whitelist in a third-party config key) — use the accurate name when referring to the actual identifier and the inclusive term when referring to the concept. And enforcing these with a linter rather than a review comment is better for everyone: it's not a person correcting a person.

The alex Vale package covers most of this out of the box.

Enforcement levels

Start with errors limited to terminology and a small banned-word list, and everything else as warnings. A linter that blocks a PR over sentence length on day one gets disabled by the end of the week. Tighten as the team gets comfortable.

Best Practices

Keep the project supplement to one page

Google's guide is hundreds of pages and nobody reads it front to back — they search it. Your supplement should be short enough to read once during onboarding: terminology, code conventions, and your deviations. Everything else defers to the base guide.

Enforce mechanically, review for substance

Reviewers should be checking whether the documentation is correct and useful. Terminology, passive voice, and heading case are things a machine catches better and without social cost. Freeing reviewers from style policing improves the review.

Include real examples of correct and incorrect

Abstract rules get interpreted differently by everyone. Paired examples don't.

Ban the minimizing words

"Simply," "just," "easy," "obviously," "of course." They add nothing, and they make a reader who is stuck feel stupid — which is exactly the reader most in need of the documentation. This is the cheapest tone improvement available.

Version the style guide with the docs

It lives in the repo, changes through PRs, and the Vale configuration lives beside it. A style guide in a separate wiki drifts from the rules actually being enforced, which is confusing in a specific and irritating way.

Add rules from real review comments

When you find yourself leaving the same feedback twice, that's a rule. This keeps the guide grounded in actual problems rather than in hypothetical ones, and it keeps it short — you only add what has come up.

Different rules for different document types

Reference pages are terse and repetitive by design; tutorials are conversational; runbooks are imperative and stripped down. Vale's per-path configuration handles this, and applying tutorial prose rules to a reference table produces noise nobody acts on.

Define code sample conventions explicitly

Which language for examples, whether to show output, how to handle secrets and placeholders, and whether samples must be runnable. These questions come up constantly and are settled once. See Docs-as-Code for testing samples in CI.

Common Mistakes

Writing a style guide from scratch

A guide with no enforcement

Terminology that isn't written down

Blocking on subjective rules from day one

Style rules with no examples

Minimizing language

FAQ

Which base style guide should we use?

The Google developer documentation style guide for developer-facing documentation — it's the most widely used in the industry, it's opinionated in useful ways, and Vale ships a package implementing much of it. The Microsoft Writing Style Guide is a better fit if your documentation spans developer and general-user audiences. Either is fine; picking one and moving on is what matters.

Is Vale worth setting up?

Yes, and the setup is about an hour. The terminology rule alone justifies it, and the false-positive rate on the standard packages is manageable once you disable the two or three rules that conflict with your voice. Run it locally too — a linter that only runs in CI means finding out about violations after opening the PR.

How do we handle terminology that comes from a third party?

Use the accurate name when referring to the actual identifier — a config key, an API field, a Git branch name — and your preferred term when referring to the concept. Document this exception explicitly, and add the third-party term to your Vale vocabulary so it isn't flagged. Renaming things that have literal names in someone else's system is worse than the inconsistency.

Does the style guide apply to code comments and commit messages?

Different documents, different needs. Commit messages usually follow their own convention (conventional commits or similar). Code comments benefit from the terminology rules and not much else. Applying full prose linting to source files produces noise. Scope Vale to docs/ and *.md, and let the terminology list inform everything else by convention.

How strict should we be with contributors on an open-source project?

Not very. A contribution with imperfect style and correct content is worth far more than one that never gets submitted because the checks were intimidating. Run the linter as a non-blocking comment on external PRs, fix the style yourself when merging, and reserve blocking enforcement for the maintainer team. See Contributing to Open Source.

Should AI-generated documentation follow the same rules?

Yes, and it's easier to enforce there than with humans — you can put the style guide in the prompt and run the same linter on the output. AI-generated prose tends to have characteristic tells: hedging, unnecessary transitional phrases, and a preference for the passive. The write-good and custom vague-word rules catch a useful share of them.

Related Topics

References