A documentation style guide should do two things: settle the arguments that would otherwise be re-litigated in every pull request, and disappear. If your team has to open it to write a page, it is too long. The working version is short: a page or two of decisions that are genuinely yours, sitting on top of an established guide you adopted wholesale, with a linter enforcing the mechanical half so no human has to.
Most style guides fail the same way. Somebody writes forty pages in month one, three people read it, and by month six the documentation and the guide disagree in a dozen places with no way to tell which is right. What follows is how to avoid that.
What is a documentation style guide for?
It is not for teaching people to write. It is for removing decisions. Every rule in it should replace a recurring conversation (how do we capitalise the product name, do we say “click” or “select”, is it an API key or a token) so that the reviewer never has to have the conversation again and the reader never sees the inconsistency.
That test is useful in both directions. If a rule has never come up in review, it does not need writing down. If the same comment appears in review three times, it does.
Adopt a guide before you write one
Almost everything you would write is already written. Adopt an established guide as your base, then document only your deviations. This is the single highest-leverage decision in the whole exercise, and it takes an afternoon.
| Base guide | Best for | Watch out for |
|---|---|---|
| Google developer documentation style guide | Developer-facing docs, APIs, SDKs. Opinionated, free, and has a matching Vale package. | Very US-English. Assumes a developer audience throughout. |
| Microsoft Writing Style Guide | Product documentation with a mixed technical and non-technical audience. | Larger and more prescriptive about voice; more to disagree with. |
| A community guide from your own ecosystem | Open-source projects whose contributors already know it. | Maintenance varies. Check the last commit before you commit to it. |
| Chicago or AP | Marketing and long-form editorial content that sits next to the docs. | Neither has anything to say about code samples, CLI syntax or UI elements. |
The first line of your style guide should be “We follow the Google developer documentation style guide, except where noted below.” Everything after that line is your actual guide, and it should be short.
The rules worth writing yourself
Five categories are genuinely local and no adopted guide can supply them.
- Product and feature names. The exact string, its capitalisation, whether it takes “the”, and what it is not called. This is the rule that gets broken most and matters most for search.
- Terminology. One term per concept, with the rejected synonyms listed beside it. “Workspace, not project, not org.” Readers who search for the rejected term still need to land somewhere, which is a job for synonyms in your search index rather than for the prose.
- Code sample conventions. Placeholder format, whether samples include the shebang and imports, which languages every sample must appear in, and whether output is shown.
- UI element conventions. How you refer to buttons, menus and fields, and whether they are bolded. Pick one and never mix.
- Page shapes. What a tutorial contains, what a reference page contains, what a concept page contains. This overlaps with information architecture, and belongs in whichever document your writers actually open.
Enforce the mechanical half with a linter
Any rule that can be checked by a machine should be checked by a machine, because a rule enforced by reviewer attention is enforced roughly half the time. Vale is the usual choice: it runs on Markdown in CI, ships packages for the Google and Microsoft guides, and takes a config file about this long.
StylesPath = styles
MinAlertLevel = suggestion
Packages = Google
[*.md]
BasedOnStyles = Vale, Google
Google.Passive = warning
Google.We = error
Vale.Spelling = errorRun it on pull requests, not on the whole corpus at once. Setting MinAlertLevel to suggestion locally and to error in CI gives writers the full advice while only blocking on the rules you actually care about.
Turning a linter on across five hundred existing pages produces a few thousand warnings and a team that disables the linter. Gate new and modified files only. The back catalogue gets fixed as it gets touched, which is the same rate at which anybody reads it.
The rules worth arguing about, and how to settle them
A handful of decisions come up on every documentation team. There is no universally right answer, but there is a right answer for you, and the point of the guide is to make it once.
Second person, or first person plural?
Use second person: “you”. It is direct, it makes the subject of every instruction explicit, and it avoids the ambiguity of “we” (does that mean the reader, the product, or the company?). Reserve “we” for statements about your own decisions: “We recommend X because Y.”
Are contractions acceptable?
Yes. “Don’t” reads faster than “do not” and is not less professional. The exception is a sentence where the negation carries real weight: a warning about data loss reads more clearly as “do not”, precisely because the expanded form is slightly slower.
Should we ban “simply”, “just” and “easy”?
Ban them, and let the linter do it. They add nothing when the step is easy and they insult the reader when it is not. The same applies to “obviously” and “of course”. This is the single most valuable rule in most style guides and the easiest one to automate.
Oxford comma?
Use it. Not because it is correct (it is a house-style choice either way) but because it removes a class of ambiguity in lists of technical terms, and because arguing about it twice costs more than the character it saves.
Present tense, or future?
Present. “The command returns a job ID”, not “will return”. Documentation describes how a system behaves, not what will happen at some point after you finish reading the sentence.
How long should a style guide be?
Short enough that a new writer can read it in fifteen minutes and remember most of it. In practice that is one page of local rules plus a link to the guide you adopted. If yours is longer, most of the excess is either duplicating the base guide or describing things that should be templates instead.
A style guide nobody can hold in their head is not a style guide. It is a document you cite after the fact to justify a review comment.
Templates carry more weight than prose here. A page template with the required headings pre-filled enforces structure more reliably than three paragraphs describing the same structure, because it is present at the moment of writing rather than at the moment of remembering.
Keep it alive
A style guide decays like any other document. Four habits keep it honest.
- Every new rule cites the review comment that prompted it. If you cannot point at a real disagreement, the rule is speculative.
- Every rule has an owner’s name on it, so somebody can be asked why.
- Rules that the linter enforces are marked as such, so nobody wastes review attention on them.
- The guide is reviewed once per release, alongside the changelog: a renamed feature invalidates a terminology rule, and nobody notices otherwise.
If your style guide lives beside your documentation rather than in a wiki nobody opens, it gets read. Doku renders it as an ordinary doc page with the same search, sidebar and anchors as everything else. See Structure for how to slot it in.