TS-26: Technical Writing Style Guide

This technical standard covers how to write technical documentation. Topics include voice and tense, headings, terminology, formatting conventions, and other prose-level and presentational rules that apply within any individual document.

For what documentation a project should have, where it lives, who it’s for, and how it’s kept current, see TS-25: Technical Documentation.

Voice and tense

Prefer active voice over passive voice. "The server rejects invalid requests" is clearer than "invalid requests are rejected by the server." Passive voice is acceptable when the actor is genuinely unknown or irrelevant to the point being made.

Prefer present tense when describing current system behavior: "the function returns null" rather than "the function will return null." Reserve future tense for describing what will happen as a consequence of an action the reader takes, and past tense for historical records such as changelogs.

Address the reader directly as "you" in instructional content ("run the following command") rather than an impersonal construction ("the user should run the following command"). This keeps instructions unambiguous about who is meant to act.

Avoid first-person plural ("we") to refer to the software itself – "the API returns an error," not "we return an error." Reserve "we" for genuine statements of the author’s or team’s position, such as in a design rationale.

Headings

Use sentence case for headings ("Referencing style guides"), not title case ("Referencing Style Guides"). Sentence case is faster to read, easier to write consistently, and avoids the ambiguity of which words to capitalize in a title-case scheme.

Headings SHOULD describe the content that follows, not tease it or ask a question. Prefer "Configuration options" over "What can you configure?"

Do not skip heading levels (for example, jumping from a level-1 heading to a level-3 heading). This breaks the document outline and assistive-technology navigation. Nest headings only as deeply as the content actually warrants. A document with only two or three headings does not need every level of the hierarchy.

Terminology

Use one term per concept, consistently, throughout a document and ideally across a body of documentation. Do not vary vocabulary for the sake of stylistic variety – "endpoint," "route," and "handler" should not be used interchangeably to refer to the same thing, because a reader will assume a change in wording signals a change in meaning.

Where a project has domain-specific or otherwise non-obvious terms, maintain a glossary and link to it on first use within a document rather than redefining the term inline every time.

Prefer the simpler, more common word where two words mean the same thing in context – "use" over "utilize," "help" over "facilitate," "start" over "initiate." Plain words are easier to translate, skim, and understand for non-native readers.

Abbreviations and acronyms

Spell out an abbreviation or acronym in full the first time it’s used within a document, with the short form in parentheses, and use the short form thereafter: "content delivery network (CDN)."

Exceptions are acronyms so common in a software engineering context that spelling them out would be noise to the target audience (for example, HTTP, URL, JSON). Use judgement based on the document’s audience.

Do not invent new abbreviations for a document unless they will be used often enough within it to justify the reader learning them. A one-off abbreviation saves the writer a few keystrokes at the cost of the reader’s comprehension.

Inclusive and plain language

Prefer neutral terminology over terms with violent, ableist, or otherwise unnecessary connotations where a clear alternative exists and is in common use – for example, "allowlist/denylist" over "whitelist/blacklist," "primary/replica" over "master/slave." The goal is precision and professionalism, not euphemism for its own sake.

But where an established technical term has no accepted neutral alternative, do not force an awkward substitute.

Avoid idioms, sports metaphors, and culturally specific references that may not translate for an international or non-native-English-speaking audience. Plain, literal language is more reliably understood than a colorful turn of phrase.

Write in a way that assumes competence in the reader’s own domain but not in yours. Don’t talk down to an experienced engineer who is simply unfamiliar with this particular codebase.

Emphasis

Use monospace formatting for anything a reader might type or that the system might output literally: file paths, commands, flags, environment variables, code identifiers, and configuration keys. Example: set LOG_LEVEL in .env.

Use bold for UI elements the reader must interact with: button labels, menu items, field names.

Use italics sparingly, mainly to introduce a new term at its point of definition, or for genuine emphasis of a word within a sentence. Do not use italics as a substitute for bold or monospace.

Do not stack multiple forms of emphasis (bold italic monospace). Pick the one that matches what the text represents.

Admonitions

Use admonition blocks (NOTE, TIP, IMPORTANT, WARNING, CAUTION) to call out information that a reader could reasonably skip in a linear read-through but should not miss – not as a substitute for well-organized prose.

Available admonitions in AsciiDoc are:

  • NOTE: Supplementary information that adds context but isn’t required to complete the task at hand.
  • TIP: An optional suggestion that makes the task easier or faster.
  • IMPORTANT: Information required to complete the task correctly; skipping it leads to a wrong but not necessarily harmful outcome.
  • WARNING: An action or condition that could cause data loss, security exposure, or other significant harm.
  • CAUTION: A risk of a less severe but still undesirable outcome, such as a deprecated approach.
[NOTE]
====
Supplementary context goes here.
====

Use admonitions sparingly. A document with an admonition on every paragraph trains readers to skip them all.

See TS-28: AsciiDoc for the full admonition syntax, including the complex block form.

Lists

Use a numbered list when the order of items matters, such as steps in a procedure. Use a bulleted list when the order does not matter.

Keep list items grammatically parallel. If the first item starts with an imperative verb, every item should. Do not mix sentence fragments with full sentences in the same list.

Punctuate list items as sentences (capitalized, full stop) when any item is a full sentence.

Before deploying, complete the following checks:

* Run the full test suite and confirm it passes.
* Review the changelog for breaking changes.
* Notify the on-call engineer of the deployment window.

Alternatively, list syntax may be used to visually separate items within a sentence that are delimited by semicolons. Example, the following is a single sentence, with the list syntax used only for presentation purposes:

Design docs:

* surface design issues early;
* help to build consensus around a design;
* ensure cross-cutting concerns are considered from the start;
* and they scale and distribute knowledge within the organization.

Rarely, items in a list may not form proper sentences. This is acceptable where the list items are the names of things in a collection. Example:

The following browsers are supported:

* Chrome
* Firefox
* Safari
* IE 10+
* Edge

Avoid nesting lists more than two levels deep. Restructure into subsections instead, since deeply nested lists are hard to scan.

Links

Link text SHOULD describe the destination, not the act of clicking. Prefer "see the deployment guide" over "click here" or a bare URL. Descriptive link text remains meaningful out of context, which matters for screen readers and for anyone scanning a page for relevant links.

Where a document will be read in both hypermedia and print/plain-text form, consider appending the full URL after the link text so the reference survives outside a hyperlinked medium.

Prefer linking to the canonical or most stable version of a resource, eg. a specific documentation version rather than a "latest" alias that will change underneath the link.

Numbers, dates, and units

Spell out numbers zero through nine in prose. Use numerals from 10 upward.

Always use numerals for measurements, versions, and anything paired with a unit (8 GB, v2, 3 retries), regardless of magnitude.

Write dates in ISO 8601 format (2026-07-02) in technical documentation, since it sorts correctly as a string and is unambiguous across locales. Avoid the MM/DD/YYYY and DD/MM/YYYY formats entirely, as both are ambiguous without knowing the writer’s locale.

Leave a space between a numeral and its unit (10 ms, not 10ms), except for percentages (10%) and degrees, which are conventionally set without a space in technical writing.

Use consistent units within a document. Do not mix, for example, milliseconds and seconds for durations of the same kind of thing without a clear reason.

Code blocks

Placeholders

Prefer to use angle brackets (<>) to encapsulate any placeholder text that is intended to be swapped for a value, such as a file name or a command line argument.

Use square brackets ([]) to indicate optional arguments.

For example:

./run <script> [<script-args>]

CLI commands

Do not prefix CLI commands with a dollar sign ($), as is common in many technical documents. This is because the dollar sign is not universally used to indicate a command prompt, and it can be confusing for readers who are not familiar with this convention.

In addition, some rendering systems will provide functionality for users to easily copy the content of code blocks, allowing the commands to be pasted directly into terminals. Inclusion of prompts invalidates the commands, making for a poor user experience.

```sh
git clone git@<hostname>:<group>/<project>.git
```

The exception to this rule is when documenting the output from CLI commands. In this case, including the prompt can help to clarify which lines are commands and which lines are output. Example:

$ heroku logs --help
display recent log output

USAGE
  $ heroku logs

OPTIONS
  -a, --app=app        (required) app to run command against
  -d, --dyno=dyno      only show output from this dyno type (such as "web" or "worker")
  -n, --num=num        number of lines to display
  -r, --remote=remote  git remote of app to use
  -s, --source=source  only show output from this source (such as "app" or "heroku")
  -t, --tail           continually stream logs
  --force-colors       force use of colors (even on non-tty output)

DESCRIPTION
  disable colors with --no-color, HEROKU_LOGS_COLOR=0, or HEROKU_COLOR=0

EXAMPLES
  $ heroku logs --app=my-app
  $ heroku logs --num=50
  $ heroku logs --dyno=web --app=my-app
  $ heroku logs --app=my-app --tail

Referencing

There are a number of conventions for including citations and reference lists within documents, such as Harvard, APA, MLA, Chicago, and Vancouver. Most conventions involve two parts:

  1. A short inline citation within the text.
  2. A full reference at the end of the text.

My preference is the Chicago style of placing an inline superscript number that cross-references a footnote or endnote. In hypermedia formats such as HTML, the inline citation is hyperlinked to its corresponding footnote, and vice versa, so readers can jump to the footnote and back again.

Where I want to reference works listed in a bibliography section at the end of the document, I will use the Harvard style for the inline citation. Example:

(Johnson, 2020)

The author names are written exactly as they appear in the reference list (see below).

I use the same formatting convention for references whether they appear in footnotes or bibliographies. My convention is a mix of the Chicago and Harvard styles. It places emphasis on the author and publication date:

<author> (<year>). _<title>_. <publication>

Example:

Johnson, M (2020). The Future of Learning. Horizon Press

When there are two authors, I write only their surnames:

Smith and Jones (2020). Title of the work. Publication

When there are three: "Smith, Jones, and Patel". When there are more than three authors, I will truncate to "Smith et al".

In hypermedia formats, the title may be hyperlinked. When printed, the full URL (including the https:// schema) should be appended to the end, after the publication. For academic journals it is common practice to include the issue number and page range of the source material. Example:

DeLorne and Fedler (2003). Journalists' Hostility Toward Public Relations: An Historical Perspective. Public Relations Review, volume 29, issue 2, pages 99-124. https://www.sciencedirect.com/science/article/abs/pii/S0363811103000195

For consistency, citations of press releases, news stories, and blog posts should follow the same format. However, as a general rule it is preferable to cite the organization or publisher as the author, even if the article has a byline. The following example is a reference for a company’s annual report:

Cision (2016). Inside PR 2026. https://www.cision.com/resources/guides-and-reports/2026-inside-pr-report/

The following example is a reference to a news story published on the PR Week website. The article has a byline, giving the name of the journalist who wrote the article. But it is more appropriate to cite the name of the publisher, as that is a more accurate reflection of the authorship.

PR Week (2025). Equiniti to acquire Notified from West Technology Group. https://www.prweek.com/article/1910473/equiniti-acquire-notified-west-technology-group

Punctuation

Colons

Only use a colon to introduce a list. The list may be written as list syntax over subsequent lines, or, for a single sentence, as items on the same line delimited by semicolons.

Do not use a colon to join two independent clauses that could each stand as a sentence on their own. Write them as separate sentences instead.

Bad:

Early in a project, when the right design is not yet clear, unstructured prose is often a better problem-solving tool than code: it is more concise, faster to produce and digest, and communicates at a higher level than code can.

Good:

Early in a project, when the right design is not yet clear, unstructured prose is often a better problem-solving tool than code. It is more concise, faster to produce and digest, and communicates at a higher level than code can.

Semicolons

Prefer two separate sentences over a semicolon joining two independent clauses. A semicolon signals a closer relationship between the clauses than a full stop does, but that relationship is rarely load-bearing enough to justify the harder read. Reserve the semicolon for joining short items in a list written inline, or for the rare case where splitting the sentence would lose an explicit contrast or cause-and-effect the semicolon itself is signaling.

Bad:

The cache is invalidated on write; this keeps reads consistent with the latest data.

Good:

The cache is invalidated on write. This keeps reads consistent with the latest data.

Sentences and paragraphs

Prefer simple sentences that express one idea each. Avoid joining two independent clauses with a hyphen, colon, or semicolon when they could instead be split into two separate sentences. A reader has to hold a joined clause in working memory until they reach the end of it before they can parse the meaning of either half. Two short sentences let the reader process and discard each idea in turn.

For example, prefer:

The cache is invalidated on write. This keeps reads consistent with the latest data.

over:

The cache is invalidated on write - this keeps reads consistent with the latest data.

Punctuation-joined clauses are still appropriate where the clauses are genuinely one thought, such as a short list introduced by a colon, or where splitting the sentence would lose an explicit cause-and-effect or contrast that the punctuation itself is signaling. Use judgment. The rule is a default, not an absolute prohibition.

Vary sentence and paragraph length to create pace. A run of uniformly medium-length sentences reads as monotonous, and a run of uniformly short sentences reads as curt. Follow a longer, more detailed sentence with a short one that lands the point. Like this. See? Varies sentence length like this creates a sense of flow and pace.

Similarly, alternate longer paragraphs that develop or qualify an idea with shorter paragraphs, or single-sentence paragraphs, that state a conclusion or transition plainly. Short paragraphs land points, longer ones carry the detail and connective reasoning between them.

AI writing tells

Text drafted or assisted by an LLM tends toward certain patterns that a human editor should recognize and remove. These patterns are not wrong grammatically, but they read as generic, evasive, or hollow, and they erode a reader’s trust once recognized. Treat this section as a checklist to apply during editing, not a rule to write to at first draft.

Inflated significance

Avoid language that asserts importance rather than demonstrating it: "stands as a testament to," "marks a pivotal moment," "underscores the importance of," "plays a crucial role." State what happened and let the reader judge its significance.

Bad: "The migration marks a pivotal moment in the platform’s evolution."

Good: "The migration removes the last dependency on the legacy queue."

Vague attribution

Avoid crediting claims to unnamed authorities: "industry reports suggest," "experts argue," "some critics believe." If a claim needs a source, name it. If it does not, state the claim directly.

Formulaic "challenges" framing

Avoid the reflexive despite-challenges structure ("Despite these challenges, the project continues to…​") and generic closing sections such as "Future outlook" or "Challenges and legacy." These add length without adding information. State specific problems and specific plans, or omit the section.

Hollow "-ing" clauses

Avoid trailing participial clauses that restate the sentence’s point in vaguer terms: "…​, ensuring reliability," "…​, highlighting its flexibility," "…​, reflecting the team’s commitment." If the clause is not adding a new, concrete fact, cut it.

Promotional language

Avoid marketing-register words in technical writing: "boasts," "vibrant," "cutting-edge," "seamless," "robust" used as a filler compliment, "in the heart of," "nestled." Technical documentation states facts; it does not sell.

Unearned superlatives and buzzwords are the same problem in a different guise: "revolutionary," "game-changing," "next-generation," "best-in-class," "state-of-the-art," "powerful," "intuitive," "elegant." If a claim like this is true, replace it with the specific, verifiable fact that makes it true. If no such fact exists, delete the claim.

Bad: "A powerful, intuitive API for managing subscriptions."

Good: "An API for managing subscriptions, with one call per lifecycle event."

Vague benefits

Avoid stating a benefit without the specific mechanism or measurement behind it: "enhanced productivity," "improved workflow," "streamlined process," "optimized performance," "increased efficiency." For each, ask what the underlying fact is – faster at what task, by how much, which steps were removed – and state that instead.

Bad: "The new indexer delivers optimized performance."

Good: "The new indexer cuts cold-start query time from 4s to 300ms."

Information priority

Lead with the fact the reader needs, not the buildup to it. State what changed, what is now possible, or how something works in the first sentence. Save background, rationale, or philosophy for after the load-bearing fact, not before it.

Bad: "We’ve been listening to user feedback, and after months of work, we’re pleased to share a new caching layer."

Good: "Responses are now cached for 5 minutes. This removes the need for clients to implement their own caching."

Overused vocabulary

Certain words are disproportionately common in LLM output and read as a tell when they appear often: "delve," "crucial," "leverage," "foster," "landscape" (used abstractly), "tapestry," "testament," "underscore" (as a verb), "robust," "seamless," "intricate." None is forbidden outright, but if a document leans on several of these, rewrite with plainer words.

Copula avoidance

Avoid replacing a plain "is/are/has" with an inflated verb: "serves as," "stands as," "represents a," "boasts a," "features a." Say what a thing is directly.

Bad: "The gateway serves as the entry point for all inbound traffic."

Good: "The gateway is the entry point for all inbound traffic."

Negative parallelism and rule-of-three padding

Avoid "not only…​ but…​" and "it’s not just X, it’s Y" constructions used for rhetorical effect rather than genuine contrast. Avoid padding sentences and lists to a rhetorical three items when two would say it, or four are true.

False ranges

Avoid "from X to Y" constructions where X and Y are not points on a real scale, used only to suggest breadth. "From onboarding to offboarding" is fine if the document actually spans that range end to end; "from data structures to the mysteries of the universe" is padding.

Chatbot artifacts and sycophancy

Technical documentation is not a chat transcript. Do not include conversational framing left over from drafting: "Great question," "Certainly!," "I hope this helps," "Let me know if you’d like me to expand on this," "You’re absolutely right that." Delete these on review; they should never reach a published document.

Knowledge-cutoff hedges

Avoid disclaiming uncertainty in vague terms: "as of my last update," "details are limited," "based on available information." If a fact is uncertain, state what is actually known and its source, or state plainly that it is not yet known.

Filler phrases and hedging

Cut filler that adds words without adding meaning: "in order to" → "to"; "due to the fact that" → "because"; "at this point in time" → "now"; "it is important to note that" → delete; "has the ability to" → "can."

Avoid stacked hedges that dilute a claim past usefulness: "could potentially possibly," "it might be argued that." State the claim with the confidence it actually deserves, once.

Generic positive conclusions

Avoid closing a section with an unearned, content-free upbeat statement: "the future looks bright," "exciting times lie ahead." End on the last concrete fact or the actual next step instead.

Uniform rhythm

Text where every sentence is close to the same length, and every paragraph the same shape, reads as mechanically generated even when each sentence is individually correct.

Stacked em dashes and bold

Overusing em dashes for parenthetical asides, or bolding many phrases within running prose, are also common tells.

Colon and semicolon overuse

Overused colons and semicolons are a common AI writing smell. Almost any sentence built around a semicolon can be split into two plain sentences, and a colon should only ever introduce a list, never an explainer clause. See Punctuation for the full rules and examples.

Review pass

After drafting, re-read the text and ask: what here would make a reader suspect this was written by an LLM rather than edited by a person? Revise anything that stands out, and prefer edits that add a concrete detail over edits that simply delete a flagged word.

References

A more extensive list of style guides is maintained on Wikipedia.