Documentation writing style guide

Notes for writing engineering documentation: reference pages, how-to guides, tutorials, READMEs, runbooks, release notes, design docs, and blog posts. The goal is prose that reads like a competent engineer wrote it. Obvious AI-generated text costs credibility with a technical audience and reads as low effort regardless of the quality of the underlying work. Documentation adds a second requirement on top of that: it must stay unambiguous for a reader who is in a hurry, under stress, or reading in a second language. Section 7 adopts ASD-STE100 (Simplified Technical English) for that reason.

0. The goal is a human voice with controlled clarity

Read this first. Everything below is a set of heuristics toward clear prose a person would write. Do not treat it as a checklist to satisfy mechanically.

Over-correction is its own tell. Prose that dodges every banned word but comes out clipped, choppy, and stripped of personality lands in a different uncanny valley. Keep the occasional analogy or aside where the document type allows it.
Do not swap one crutch for another. If every em-dash becomes a parenthesis, parentheses become the new tell. If banned words become near-synonyms, nothing changed.
On the dash rule specifically: a single deliberate em-dash from a human reads fine. The tell is the reflexive, high-frequency habit. The rule here stays at zero because a generator cannot reliably tell its reflexive dash from a deliberate one, so the safe default is none. Apply that spirit everywhere.
Different document types get different registers. Procedures, reference pages, runbooks, and release notes follow ASD-STE100 strictly (section 7). Conceptual overviews, design docs, and blog posts keep the vocabulary and terminology discipline while they relax the sentence-length caps.

1. Punctuation

No em-dashes or en-dashes (—, –). This is the single loudest AI tell. Replace with:
- a comma, when the aside is mild: rewrite "the server fetches it — then parses" as "the server fetches it, then parses";
- parentheses, when it is a true aside: "the metadata endpoint (only reachable from inside the instance)";
- a colon, when the second half explains the first: "one design fact: the server fetches a URL a stranger chose";
- a period. Two shorter sentences usually beat one dash-spliced sentence, and shorter sentences also satisfy section 7.
Do not replace an em-dash with " - " (spaced hyphen). That is a different tell. Restructure instead.
Use hyphens only for compound modifiers ("threat-model-first", "self-contained") and to break long noun clusters (section 7).
No arrows (→, ->, =>, ⇒) in prose or headings. "input → output", "v1 → v2 migration", "Problem → Solution" all read as generated shorthand, and STE requires a verb anyway. Write the relationship out: "the parser turns the input into an AST", "upgrade from v1 to v2". Arrows stay where they are literal syntax: inside code blocks, and in UI navigation paths when you follow the product's own convention ("Settings > Privacy > Permissions").
Straight quotes and apostrophes are fine; do not fuss over curly vs straight.
Avoid the ellipsis "…" for trailing-off drama.
Avoid exclamation points in documentation. Enthusiasm punctuation reads as marketing.

2. Words and phrases to avoid

These are overused by LLMs and read as AI filler. Cut them or say the plain thing.

Nouns / metaphors:

load-bearing (as in "the load-bearing assumption")
landscape ("the research landscape"); "the research on X" is fine
realm, world ("in the realm of", "the world of")
tapestry, symphony, orchestra
testament ("a testament to")
cornerstone, bedrock, linchpin
treasure trove, wealth of, myriad, plethora
game-changer, game-changing, paradigm shift
deep dive, "let's dive in"
compass needle / north star (as metaphor)
journey ("your onboarding journey")
silver bullet, low-hanging fruit, double-edged sword, Swiss Army knife
magic, magical ("it magically reconnects"); describe the mechanism instead

Verbs:

delve, delve into
leverage, utilize (use "use")
underscore, highlight (as in "this underscores"); use "shows"
unlock, unleash, supercharge, turbocharge
elevate, empower, harness
boast ("the tool boasts X")
foster, cultivate
navigate (metaphorical)
streamline (as filler)
embark on
earn their keep, pull their weight

Adjectives:

robust, seamless, seamlessly
crucial, pivotal, vital, paramount
cutting-edge, state-of-the-art (unless literally citing SOTA research)
meticulous, meticulously
comprehensive, holistic
rich (as in "rich, actionable insights")
powerful (as filler)
elegant, elegantly
intuitive, effortless, delightful (as filler)
blazing fast, lightning-fast

Tech-doc filler:

"at scale"
"under the hood" (overused)
"battle-tested"
"first-class citizen"
"out of the box"
"sane defaults"
"the beauty of X is"
"essentially", "basically" (as filler)
"Pro tip:", "Fun fact:", "Spoiler:"

Minimizing words:

"just", "simply", "of course", "obviously". "Just run this command" and "simply configure the webhook" alienate the reader who is stuck precisely because it was hard. Cut the minimizer and describe the actual steps.

Bureaucratic inflation (also banned by STE):

"in order to": write "to"
"prior to": write "before"
"in the event that": write "if"
"utilize": write "use"
"aforementioned": name the thing again

Connectives / filler openers:

"It's worth noting that", "It's important to note", "Notably,", "Crucially,", "Importantly,"
"Interestingly,", "Surprisingly,", "Arguably," as sentence openers
"Furthermore," / "Moreover," (once in a while is fine; keep it out of every paragraph)
"In today's fast-paced world", "In an era of"
"At the end of the day"
"Here's the thing:", "Here's the kicker:"
"Let's unpack this"
"That said," (overused)
"Rest assured"
"Needless to say" (if it is needless, delete it)
"Honest ___" as a label ("Honest limits", "Honest caveat", "To be honest"). State the caveat.

3. Contrastive reversal and rhetorical cadence (the loudest tell)

This is the pattern peer reviewers flag first, so treat it as the top priority. State the point directly on the first pass. Do not set up a weak or obvious framing to reveal the "real" point in the next sentence.

Ban the "not X, but Y" family in all its forms: "not X, but Y", "it's not X, it's Y", "the issue isn't X, it's Y", "it wasn't X, it was Y", "not just X, but Y", and the trailing-contrast "X, not Y".
Ban the affirmative twin, "It's X, not Y." "It's a cache, not a database." "This is a warning, not an error." The sentence leads with the fact and then spends its second half on a thing the reader never claimed. State what it is and, when the confusion is real and common, add a separate sentence that names the specific mistake: "This is a cache. Data in it can disappear at any time."
Also ban the softer pivots when used for contrast: "rather than", "instead of X, do Y". Say what to do.
- Bad: "Treat the numbers as directional signal, not proof."
- Good: "This is a sample size of one, so the counts are a rough signal and the exact numbers are noisy."
No mirrored sentence pairs for emphasis. Do not restate the same idea with slightly different wording for drama. Avoid thesis-antithesis cadence, binary contrast framing, fake-outs, over-signposted pivots, and presentation-style escalation.
- Bad: ""Validate inputs" is noise; naming the real threat is signal."
- Good: "Name the asset an attacker wants and the data flow that reaches it."
Write flat, direct, decisive. Say the point once. Add nuance only when it changes the meaning. Prefer plain diagnosis over rhetorical structure. A direct negation used to state a fact ("it does not catch subtle flaws") is fine; the banned thing is the setup-then-reveal rhythm.

4. Sentence, structure, and formatting patterns to avoid

These are structural tells: the phrasing rhythm and layout, on top of the individual words in section 2.

Verbless sentences. Punchy fragments dropped in for emphasis: "No exceptions." "Every time." "Full stop." "Fast. Reliable. Open source." Write complete sentences. An imperative ("Delete the key.") contains a verb and is fine; the ban targets the fragment used as a drum hit.
The dramatic one-liner reveal. "Read that again." "And that changes everything." "The difference is the whole lesson." Allow one per document at most, and none in reference material.
The colon-drama reveal. "The punchline up front:", "The result:", "The kicker:". Occasional use is fine; it becomes a tic fast.
Rule of three everywhere. "faster, cleaner, safer." "the what, the why, and the how." Real writing varies list length; a three-beat list in every paragraph is a tell.
Rhetorical-question section openers. "So what does this actually mean?" "But how does it work?" State the point, or ask a real question and immediately answer it with something the reader could not guess.
Telling readers what they think or feel. "You've probably hit this." "We've all been there." "If you're like me, you…" Assume a smart reader and get to the content.
Whether-you-clause openers. "Whether you're a solo dev or an enterprise team, …" Cut it.
The good-news/bad-news frame. "The good news is X. The bad news is Y." State X and Y as facts.
Reflexive "Think of X as Y" analogies. One real analogy that carries weight is fine. The reflex of opening every concept with a forced comparison ("Think of Kubernetes as an orchestra conductor") reads as generated.
Fake dialogue with the reader. "Wait, what?" "Yes, really." "I know what you're thinking." Cut it.
Over-signposting. "Here's the most useful part." "Now for the interesting bit." "The key takeaway is." Say the thing and let it be interesting on its own.
Tour-guide transitions. "Now let's look at…" "Having covered X, let's turn to Y." "As we can see above." Headers and paragraph breaks already do this work.
Formulaic section labels. "X, in one paragraph." "The TL;DR." "In a nutshell." Name the section for what it contains ("The results", "How we tested", "Configuration").
Hedge-and-pivot. "While X is true, it's also true that Y." Say Y.
Summary sentence that restates the paragraph. LLMs end paragraphs by re-summarizing what they said. Delete the last sentence if it only repeats.
"In other words" / "Put simply" restatements. If the first version was clear, cut the second. If it was unclear, fix the first version.
Empty superlatives. "dramatically", "vastly", "incredibly", "remarkably". If the number is dramatic, the number carries it.
Bold-for-drama. Do not bold whole sentences for emphasis. Reserve bold for genuine scannable keywords: UI labels, flag names, the term a definition defines.
Bulleting everything. Prose is the default. Reserve bullets for genuinely parallel, scannable items, for option lists, and for procedure steps. (A style guide is one of the few documents where dense bulleting is correct, so this file is the exception and a poor model for article prose.)
Emoji in headers or as list markers (✅ ❌ 🚀 🔥). Reads as content marketing.
Tables doing a sentence's job. Tables earn their place for real multi-dimensional comparison and for reference material (parameters, error codes, limits). A two-row "Feature / Benefit" table does the job of one sentence.

5. Document shape: openings, closings, headings, terminology

Document-level structure gives away a generated draft as fast as any sentence does.

No throat-clearing intro. Cut "In this post, we'll explore…", "This guide will walk you through…", and the bulleted "what you'll learn" preview. A how-to opens with what the reader can do when they finish. A blog post opens on the problem, a concrete failure, or the surprising result. A reference page opens with one sentence that says what the thing is and does.
No recap conclusion. Cut "In conclusion, we've explored…" and any closing list that repeats the document. End a how-to with next steps or links to related tasks. End a blog post on the consequence or the thing you would do next, or stop.
Kill the "Enter X" product reveal. "Enter Kubernetes." "That's where Redis comes in." Introduce the tool by what it does.
Titles and headings. Avoid the content-mill shapes: "The Ultimate Guide to X", "Mastering X", "X: A Comprehensive Guide", "Why X Is the Future of Y", "N Ways to…". For how-to material, use task headings with a verb ("Rotate an API key"). For reference material, use noun phrases ("Configuration options"). For blog posts, state the specific claim or result ("We cut p99 latency 40% by deleting a cache").
One name per concept. Pick one term for each concept and repeat it everywhere: in headings, prose, code, and the UI. Synonym variation for elegance ("the service", "the daemon", "the agent" for one program) creates ambiguity, breaks search, and is also an STE violation.
Present tense for system behavior. Write "The server returns 429 when the quota is used", and reserve "will" for genuine future events such as a deprecation date.
Date-stamp or version-stamp anything that rots. Benchmarks, screenshots, pricing, and default values change; anchor them to a version or a date so the reader can judge staleness.

6. Code, commands, and procedures

The code is often where a generated document gives itself away, even when the prose is clean.

Do not narrate the code after the block. LLMs paste a snippet and walk it line by line: "First we import the client, then we define the handler, then we loop over the results." If the code is readable, the walkthrough is filler. Explain the non-obvious decision, the gotcha, or the reason it is written that way.
Comment only where a reader would actually wonder. Delete comments that restate the line (# increment the counter above i += 1).
Use realistic values. foo/bar/baz, example.com everywhere, and your_api_key_here read as synthetic. Plausible names (checkout_service, user_id, a real-looking path) read as code that ran. Mark true placeholders explicitly (<CLUSTER_NAME>) and say they are placeholders.
Do not present untested code as tested. If you did not run it, label it a sketch. A technical reader will run it and find out.
Keep snippets minimal. Show the lines that matter and elide the boilerplate with # .... A 40-line block where 5 lines carry the point buries the point.
One action per procedure step. Number steps that the reader performs in order. Put the purpose before the action when the reader needs it to decide: "To enable TLS, set tls.enabled to true."
Show expected output. After a command that prints something, show what success looks like, trimmed to the lines that matter.
Quote error messages verbatim. Readers arrive by pasting the error into a search box; a paraphrased error is unfindable.

7. ASD-STE100 (Simplified Technical English)

Procedures, reference pages, runbooks, warnings, and release notes must comply with ASD-STE100. Conceptual overviews, design docs, and blog posts keep the vocabulary and terminology rules and may exceed the length caps when a longer sentence is clearer. The core rules:

Length caps. Procedural (instruction) sentences: 20 words maximum. Descriptive sentences: 25 words maximum. Paragraphs: 6 sentences maximum, one topic per paragraph.
One instruction per sentence. Split compound instructions: "Stop the service. Then delete the lock file."
Imperative mood for instructions. Write "Remove the panel", never "The panel should be removed" or "You will want to remove the panel."
Active voice. Required in procedures. In descriptive text, use the passive only when the agent is unknown or irrelevant.
Simple tenses only. Use the simple present, simple past, and simple future. Avoid the perfect tenses ("has returned", "had been configured") and avoid -ing verb forms except in established technical names ("logging", "load balancing").
One word, one meaning. Use each word in one part of speech and one sense. If "test" is your noun, write "do a test" and do not also use "test" as a verb.
One name per thing. Same rule as section 5, enforced strictly here.
Break noun clusters. Three nouns maximum in a row. Rewrite "container image vulnerability scan report schedule" with prepositions or hyphens: "the schedule for vulnerability-scan reports on container images."
Keep the articles. Write "Connect the cable to the port", never the telegraphic "Connect cable to port."
No idioms, slang, or Latin abbreviations. Replace "e.g." with "for example", "i.e." with "that is", and "etc." with a complete list or "and more" with the boundary stated.
Warnings and cautions come before the step they protect, start with a clear command, and state the consequence: "Do not delete the volume. Deletion is permanent and destroys all snapshots."

STE exists so that a stressed reader, a non-native reader, and a machine translator all get one possible meaning per sentence. When an STE rule and a voice rule collide, STE wins in procedural and reference material.

8. The voice we want

Direct and concrete. Prefer the specific noun and the real number over the abstraction.
Vary sentence length within the caps. A short sentence lands a point; a longer one can carry a clause that earns its place.
Plain verbs: use, show, find, break, miss, fix, run, measure, set, remove.
Confident but honest about limits.
Be opinionated about the path. In a blog post, have a take: "I think reaching for an ORM here is usually a mistake, and here is the case that changed my mind" beats a neutral pros-and-cons survey. In docs, opinion takes the form of a recommendation: name one recommended approach, then say when each alternative applies. Five options presented as equals force the reader to do your job.
Calibrate confidence to what you actually did. Separate what you measured from what you are guessing. "Benchmarked on one box, so treat the absolute numbers as rough" is more credible than a bare claim or blanket hedging.
Never invent a specific to sound concrete. A made-up benchmark, a plausible-but-wrong version number, or an invented quote gets caught once, and a technical reader then discounts the whole piece. If you lack the figure, give the shape ("a few hundred milliseconds, unmeasured") or link the source. Real specifics come from real artifacts, so link the RFC, the issue, the commit, the changelog.
It is fine to start a sentence with "But" or "And" occasionally in blog prose. Contractions are fine in blog prose; prefer full forms in procedures, where STE and translation both favor them.
When in doubt, read it aloud. If you would not say it to a colleague at a whiteboard, rewrite it.

9. Quick pre-publish checklist

Search the document for — and –. There should be zero. Search for →, ->, and => outside code blocks and UI paths, and for ! outside code blocks.
Ctrl-F the section 2 words you know you lean on (leverage, robust, crucial, utilize, seamless, landscape), plus "just", "simply", "in order to", and "prior to".
Search for "not " and "It's" and check every hit against section 3: no "not X, but Y", no "X, not Y", no "It's X, not Y".
Scan for verbless fragments, paragraph-ending summary sentences, and dramatic one-liners. Delete or complete them.
Count three-beat lists. If a section has more than one, vary them.
Read the intro aloud. Cut any "This guide will walk you through" opener and any recap conclusion.
Check each section opener. If it is a rhetorical question, rewrite it as a statement.
For each code block: delete any line-by-line narration and keep only the non-obvious why. Confirm placeholders are marked and error messages are verbatim.
In procedures and reference pages, spot-check STE: count words in a sample of sentences (20/25 caps), confirm one instruction per sentence, active voice, articles present, no "e.g."/"i.e."/"etc.", and one name per concept across the whole page.
Confirm every number, version, and quote is real. If you did not measure or verify it, say so or link the source.
Scan formatting: bulleted lists that should be prose, emoji in headers, and tables that a sentence could replace.

kristovatlas/STYLE-GUIDE.md

Select an option

No results found