What Makes a Technical Writing Style Guide People Actually Follow
Almost every documentation team has a style guide. Far fewer have a style guide anyone reads past the first week. The document gets written with enthusiasm, lives in a wiki page nobody opens, and slowly diverges from how the team actually writes. A style guide that is not followed is worse than none, because it creates the illusion of consistency while delivering none of it. The secret to a successful style guide is not comprehensiveness — it is usability and enforcement.
A good technical writing style guide makes the right choice the easy choice. It answers the questions writers actually have, it is findable at the moment of doubt, and where possible it is enforced by a machine rather than a reviewer's memory. This article covers how to build one that survives contact with a real, busy team.
Why Most Style Guides Get Ignored
Style guides fail for a few consistent reasons. They are too long — a hundred pages nobody will read when they just want to know whether to write "log in" or "login." They are too abstract, full of principles like "write clearly" that give no actionable ruling. They are hard to find, buried in a wiki with no search. And they are unenforced, so following them is optional and the busiest writers skip them under deadline. The pattern behind all of these is friction: at the moment a writer has a question, the guide is slower to consult than to guess. Fixing this means designing the guide as a quick-reference tool, not a manifesto — organised for lookup, opinionated enough to give a clear answer, and integrated into the writing workflow so consulting it costs nothing.
Build on an Existing Guide, Don't Start Blank
Writing a complete style guide from scratch is a waste of months and produces something less thorough than what already exists for free. The professional move is to adopt an established guide as your base and layer only your specific decisions on top. The Google developer documentation style guide and the Microsoft Writing Style Guide are both comprehensive, free, and battle-tested across enormous product surfaces. IBM and Apple maintain excellent guides too, and the Chicago Manual of Style covers general editorial questions. Pick one as your default, state clearly "we follow the Google style guide except where noted," and then your own guide only needs to capture your product-specific terminology and the handful of places you deviate. This shrinks your maintenance burden from thousands of rules to dozens, and it inherits years of refinement you would otherwise repeat badly. For teams scaling content, this base-plus-overrides model is what keeps voice consistent across many contributors.
What Actually Belongs in Your Guide
Your layer on top of the base guide should focus on decisions specific to you. Cover voice and tone: are you formal or conversational, do you address the reader as "you," do you use contractions? Specify formatting conventions for the elements your product uses heavily — how you present code, UI element names, keyboard shortcuts, file paths, and placeholders. Define your rules for procedures: numbered steps, imperative mood, one action per step. State your conventions for links, admonitions, and screenshots. Include accessibility requirements like meaningful alt text and descriptive link text. Crucially, give examples for every rule — a rule stated abstractly is ambiguous, but "write 'select Save,' not 'click on the Save button'" is unmistakable. Keep each entry short and scannable so a writer can resolve a question in seconds.
The Terminology List Is the Core
If your team maintains only one thing, make it the terminology list: the canonical spelling, capitalisation, and usage of every product-specific term, plus the words you deliberately avoid. This is where inconsistency is most visible and most damaging — when one page says "dashboard," another "console," and a third "control panel" for the same thing, readers lose confidence. A good terminology list records the approved term, forbidden alternatives, and a short usage note. It should also cover general choices your team makes repeatedly: "email" not "e-mail," "log in" (verb) versus "login" (noun), whether to use the Oxford comma. This list is the highest-value part of the guide because it resolves the most frequent real questions and because it can be enforced automatically, as the next section covers.
Enforce With Tools, Not Nagging
A rule enforced by human reviewers relying on memory will be applied inconsistently and will breed resentment. The scalable answer is automated linting. Vale is the standard prose linter for technical documentation: you encode your style rules — banned terms, preferred spellings, passive-voice warnings, heading capitalisation — as configuration, and it flags violations in the editor and in CI before content is merged. Google and Microsoft both publish Vale rule sets for their style guides, so you can enforce your chosen base with minimal setup and add your terminology list on top. This turns the style guide from a document people are supposed to remember into checks that run automatically, freeing human reviewers to focus on clarity and correctness. Our guide on testing documentation covers wiring Vale and related checks into your pipeline.
Keep It Alive as a Living Document
A style guide is never finished. New products introduce new terms, and real writing surfaces questions the guide has not answered. Give the guide a clear owner and a lightweight process for proposing changes — often the same pull-request workflow as your docs, so decisions are discussed and recorded. When a recurring style question comes up in review, the answer belongs in the guide, not just in that thread. Version the guide alongside your content and announce meaningful changes. A living guide that grows with the team's real questions stays trusted; a frozen one drifts into irrelevance. To build one that lasts, Darlo's Style Guides & Standards course walks through creating and enforcing a guide end to end, and our free Style Guide Starter Checklist template gives you a ready structure — voice, terminology, formatting, and Vale enforcement — to adapt to your product. Explore both at /courses.
Style Guide Starter Checklist
A ready-to-adapt structure for a technical writing style guide — voice, terminology list, formatting rules, and Vale enforcement setup — so you build a guide teams follow instead of ignore.
Should we write our own style guide or use Google's or Microsoft's?
Adopt an established guide like Google's or Microsoft's as your base and layer only your product-specific decisions and terminology on top. This inherits years of refinement, shrinks your maintenance to dozens of rules, and still lets you capture what makes your product unique.
How do you get writers to actually follow a style guide?
Reduce friction and automate enforcement. Keep the guide short and scannable so lookups are fast, and use a prose linter like Vale to flag violations in the editor and CI. Machine enforcement is consistent and removes the nagging that human review requires.
What is the most important part of a style guide?
The terminology list — the canonical spelling, capitalisation, and usage of every product term plus forbidden alternatives. It resolves the most frequent real questions, is where inconsistency is most visible to readers, and can be enforced automatically.