Don't Panic — Documentation Style Guides and Terminology

A style guide is the shared notebook of writing decisions: voice, punctuation habits, heading case, how you bold an interface label, which spelling wins. Terminology is the naming half of that notebook. It picks one string for one concept, defines it, and keeps every page from inventing a synonym because Tuesday felt creative.

Without that notebook, each author builds a private dialect. Readers then meet "workspace", "project", and "tenant" for the same object, or three capitalizations of the same product name. Consistency is not etiquette. It is how documentation stops charging a translation tax on every paragraph.

Public guides such as Google's developer documentation style guide and the Microsoft Writing Style Guide already contain the common layers. Voice. Mechanics. Formatting. A word list. Inclusive language. Steal the structure. Add your product terms. The important trick is the reference hierarchy: project exceptions first, then the organization guide, then dictionaries and peer manuals when everyone is silent. Point at the rung. End the meeting.

Terminology needs four fields or it melts. Preferred term. Definition. Deprecated aliases, especially internal code names that refuse to die. Scope. A glossary tells readers what approved words mean. A termbase keeps the banned forms too, so reviewers and linters can catch the ghosts. Publishing only the pretty glossary is how drift returns wearing a friendly smile.

Requirement words such as MUST and SHOULD are a specialized dialect from RFC 2119, clarified by RFC 8174: only the uppercase forms carry special force. Most product tutorials should speak ordinary instructions instead. If a page truly needs normative key words, say so explicitly. Do not sprinkle capital letters like confetti and hope legal notices appear by magic.

Decisions become real when they enter the workflow. A short style sheet holds project exceptions. Reviews apply the hierarchy. Prose linters such as Vale encode substitutions. CI can refuse a forbidden alias. None of that proves a procedure works. Green lint means the language matches the notebook. Technical editing still has to check the facts.

Surprises worth keeping: marketing and docs may share names while keeping different tone guides; a noisy linter without product vocabularies trains everyone to ignore CI; the weekly hyphen argument is usually a missing word-list entry, not a personality conflict.

Read the Intro for the full map. Use the Cheatsheet when a conflict appears in review. The Exercise builds a tiny style sheet and termbase against a messy draft. Field Notes covers the failure modes that feel personal until you see the mechanism. Pick a base guide, record ten contested terms, and stop renegotiating English every pull request.