TS-26: Technical Writing Style Guide

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

Topics are organized alphabetically for quick lookup.

See also TS-25, which sets principles for the structure, ownership, and lifecycle of technical documentation.

This technical standard is agnostic about the source format in which technical documentation is written. See TS-27 and TS-28 for Markdown and AsciiDoc standards, respectively.

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, then use the short form thereafter. Examples: "content delivery network (CDN)", "role-based access control (RBAC)", "service level objective (SLO)".

Exceptions are acronyms so common to the audience that spelling them out would be unnecessary noise. In technical documentation, acronyms such as HTTP, URL, and JSON do not need explaining.

Omit periods from an abbreviation written in capitals: API, not A.P.I..

Do not invent new abbreviations.

Form the plural of an abbreviation by adding a lowercase "s," with no apostrophe: "three APIs," "two CDNs".

Choose "a" or "an" before an abbreviation by how it’s pronounced, not how it’s spelled: "an HTTP request" (pronounced "aitch"), "a URL" (pronounced "you").

Do not precede a pronounceable acronym with "the" where the acronym itself already functions as the noun: "JSON is a text format" not "the JSON is a text format".

Active voice

Prefer active voice over passive voice. "The server rejects invalid requests" is clearer than "invalid requests are rejected by the server." Recognize passive voice by its verb phrase, a form of "be" — eg. "am", "is", "are", "was", "were", "been" — followed by a past participle, with the sentence’s subject receiving the action rather than performing it. As a check, try appending "by <actor>". A passive sentence will accept it without changing meaning, eg. "invalid requests are rejected [by the server]".

Admonitions

An admonition is a block set apart from the surrounding prose, usually rendered as a labeled, highlighted panel, that draws attention to information a reader could reasonably skip in a linear read-through but should not miss. Depending on the tool, admonitions are also called callouts or alerts.

Use admonitions only where the document’s source format supports them natively. AsciiDoc has built-in admonition blocks, and some extensions of Markdown add them – GitHub’s alerts, for example – but core Markdown does not. Where the format has no native support, work the information into the prose instead of imitating an admonition with ad-hoc formatting.

The five conventional admonition types, shared by AsciiDoc and GitHub’s Markdown alerts, 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.

Use admonitions sparingly, for genuine asides that are secondary to a linear read-through of the document – not as a substitute for well-organized prose, and not for core content that belongs in a regular paragraph. A document with an admonition on every paragraph trains readers to skip them all.

The five criteria above are written for procedural, task-oriented content. Read them against the document’s own nature for a reference or encyclopedic document, which has no task to complete: IMPORTANT becomes a caveat or nuance whose omission would leave the reader with a wrong understanding of the concept; WARNING becomes a common misconception or practice that could cause real harm if acted on, rather than an action that could cause harm directly. The admonition types and their relative severity stay the same – only what counts as "correct" or "harmful" shifts from completing a task to understanding a concept correctly.

For the syntax, see TS-27: Markdown and TS-28: AsciiDoc.

Apostrophes

Form a singular possessive by adding 's, including for a name ending in s: "the API’s rate limit," "Chris’s PR." Form a plural possessive by adding only an apostrophe after the existing s: "the servers' response times."

Write a decade without an apostrophe before the s: "the 2020s," not "the 2020’s." Write the plural of an abbreviation or acronym without an apostrophe: "three APIs," "two CDNs," not "three API’s."

Treat a time span before a noun like "experience" or "notice" as a plural possessive, not a compound modifier: "20 years' experience," "three weeks' notice," not "20 years experience." The span is the thing the noun belongs to — "experience of 20 years" — the same genitive construction as any other plural possessive. This differs from a compound adjective built from a number and a unit, which takes a hyphen and no apostrophe instead: "a 20-year-old system".

Attributing claims

Name the source of a claim that needs one. Do not credit a claim to an unnamed authority, eg. "industry reports suggest," "experts argue," "some critics believe." A reader cannot check or weigh a source they are not told about. If a claim does not need a source, state it directly, without the borrowed authority.

Benefit claims

Do not state a benefit without the mechanism or measurement behind it. "Enhanced productivity," "improved workflow," "streamlined process," "optimized performance," and "increased efficiency" each tell the reader that something got better without saying what. Ask what the underlying fact is (faster at which 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."

Citing versions of named standards

Cite a named published standard with a version, and with a conformance level where the standard defines one: "WCAG 2.2 Level AA," not "accessible"; "TLS 1.3," not "SSL/TLS." A standard named without a version is not a testable threshold, and the statement ages badly as the standard itself evolves. This is the opposite case to avoiding a pinned version number in an illustrative code example, where a policy is being illustrated, not a testable requirement being stated.

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

Code blocks

Every code block MUST specify its language on the [source,<language>] line (bash, sh, json, and so on) so syntax highlighting renders correctly; see the repository’s style guide for the full rule. Indent code with spaces, not tabs, so the block renders consistently regardless of the reader’s editor settings.

Keep a code example narrow enough to read without horizontal scrolling in a typical rendered column — wrap or truncate a long line rather than letting it run off the edge of the page.

Collective nouns

Treat a collective noun such as "team," "committee," or "data" as singular when it refers to the group as one unit, and as plural only when the sentence is explicitly about the group’s individual members: "the team is responsible for the migration," not "the team are responsible." Treat "data" as singular in technical writing ("the data is inconsistent"), matching common software usage, even though some style guides still require the Latin plural. Do not switch a collective noun’s number partway through a document.

Colons

Do not use a colon to introduce a code block or a list block. Where a sentence leads into a list, terminate it with a period instead.

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.

The only valid use for a colon is within a single sentence that ends with a short, comma-separated list.

The model supports three operations: create, read, and delete.

Lowercase the first word after a colon, unless it’s a proper noun or the colon introduces more than one complete sentence.

The model supports three operations: create, read, and delete.

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.

Commas

Use the serial (Oxford) comma before the final item in a list of three or more: "create, read, and delete," not "create, read and delete." Omitting it can make the last two items read as a single pair.

Follow an introductory phrase or clause with a comma before the main clause, unless the phrase is very short (three words or fewer) and the sentence reads unambiguously without one.

After the request is authenticated, the gateway forwards it to the origin.
First look at the logs.

Do not splice two independent clauses together with only a comma. Either join them with a coordinating conjunction (and, but, so), split them into two sentences, or use a semicolon.

Bad:

The request failed, the client retried it.

Good:

The request failed, so the client retried it.

Contractions

Use contractions — eg. "it’s," "don’t," "can’t" — where they make a sentence read more naturally. But do not overuse them to the point that the document reads as informal or conversational, rather than as technical reference material.

Conversational framing

A published document is not a conversation. Delete framing carried over from email, chat, or a drafting session, such as "Great question," "Certainly!," "I hope this helps," "Let me know if you’d like more detail," and "You’re absolutely right that." These phrases address a correspondent, not a reader, and add nothing to the content.

Dashes

Use an em dash (—) closed up against the words on either side, with no surrounding spaces, to set off a parenthetical or an abrupt break in a sentence: "the change is backward compatible—no client update is required."

Use em dashes sparingly. A paragraph with several dash-set asides reads as fragmented and makes each aside harder to follow. Most asides read better set off by commas or parentheses, or moved to a sentence of their own.

Use an en dash (–), not a hyphen, for a numeric range or a negative number where a hyphen could be misread as a minus sign or a compound modifier: "pages 12–20," "a range of -5 to 5." Do not use an en dash as a substitute for an em dash.

Dates and times

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.

Write a time of day in 24-hour format (14:30), for the same reason ISO dates are required: it sorts correctly and is unambiguous across locales, unlike 2:30pm or 2.30pm. Where a document must show 12-hour format for a non-technical audience, write it as 2:30 pm, with a space before the lowercase am/pm and no periods.

Editing

Many of the rules in this standard are easier to apply while editing than while drafting. Write the first draft for content, then revise it against this standard.

After drafting, re-read the text as the reader will meet it. Ask what makes it read as generic, padded, or evasive, and revise anything that stands out.

Prefer an edit that adds a concrete detail over one that only deletes a flagged word. Replacing "optimized performance" with the measured speed-up fixes the sentence. Deleting "optimized" leaves a claim with nothing behind it.

eg. and ie.

Write "eg." and "ie." with periods and without a comma, "eg. the staging and production environments" not "e.g., the staging and production environments."

You may spell out "for example" or "that is", where doing so reads better.

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. Also use bold to introduce a new term at its point of definition, the first time it is used in a document.

Do not bold phrases in running prose for emphasis. Bold scattered through a paragraph competes with itself, and the reader stops treating any of it as important.

Use italics sparingly, 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.

Within a monospace span, use italic monospace for a placeholder the reader must substitute (<file>) and regular monospace for a value the reader types or the system outputs literally. Do not italicize a plain-prose mention of a URL or file name; set it in regular monospace instead, consistent with the rule above.

Exclamation and question marks

Do not use exclamation marks in technical documentation. They read as an attempt to manufacture urgency or enthusiasm the content itself does not carry — the same failure mode as promotional language. State the fact plainly instead.

Use a question mark only for a genuine question directed at the reader, such as a heading phrased as a question in a FAQ. Do not use a rhetorical question as a stylistic device to introduce a topic ("But what does this mean for performance?"); state the point directly instead.

Filler words and phrases

Cut a word that adds no meaning to the sentence it sits in — "very," "actually," "basically," "simply," "just," "quite," "really," "so," "in particular," "obviously." Test a candidate by removing it: if the sentence’s meaning is unchanged, the word was padding.

Shorten a wordy phrase to its plain equivalent. Write "to," not "in order to"; "because," not "due to the fact that"; "now," not "at this point in time"; "can," not "has the ability to." Delete "it is important to note that" outright, and let the sentence that follows carry its own weight.

Footnote and endnote mechanics

Number footnotes and endnotes per document, not restarting per section or chapter, since a merged single-page standard has no natural chapter boundary to restart at. Place the footnote marker after any adjacent punctuation, not before it: "…​as documented elsewhere.1" not "…​as documented elsewhere1." A footnote MUST contain more than a bare URL — give it enough context (author, title, or a short description) that the reference is useful without following the link.

Foreign words

Italicize a foreign word or phrase that has not been absorbed into everyday English usage, and preserve its native accents and diacritics: "the API uses a naïve Bayes classifier." Do not italicize a loanword that has become standard English vocabulary, such as "cafe" or "role" — write these in plain roman type. Where a word’s status is genuinely ambiguous, follow its spelling in an authoritative English dictionary rather than the source language’s orthography.

Grammar

The presentational and word-choice conventions elsewhere in this standard assume grammatically correct prose. This section states the specific rules most often gotten wrong in technical writing.

  • Split infinitives are permitted where the alternative is awkward. "To boldly go" is grammatically fine; do not contort a sentence to avoid placing an adverb between "to" and the verb it modifies. Prefer the unsplit form only where it reads at least as naturally.
  • Avoid a dangling participle — an introductory participial phrase whose implied subject does not match the sentence’s actual subject. "Having configured the server, the request succeeded" wrongly implies the request did the configuring; write "Having configured the server, we sent the request" or "After the server was configured, the request succeeded."
  • Use the subjunctive mood for a hypothetical, contrary-to-fact, or wished- for condition: "If the build were reproducible" (not "was"), "I wish the test suite were faster." The subjunctive uses "were" for all persons in this construction, not just plural ones.
  • A gerund takes a possessive adjective when it is the true subject of the clause: "We appreciated Priya’s explaining the tradeoffs" (the explaining is the point, not Priya), not "We appreciated Priya explaining the tradeoffs."
  • Use "an" before a vowel sound, not before a written vowel — "an SQL query" (pronounced "ess-cue-el"), "a Unix system" (pronounced "you-nix"), "an hour," "a European." The rule tracks pronunciation, not spelling.

Grammatical person

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 — eg. "Referencing style guides" — not title case — eg. "Referencing Style Guides". Sentence case is faster to read, easier to write consistently, and avoids the ambiguity of which words to capitalize.

This applies equally to document titles, not just section headings within a document. Capitalize only the first word and any proper nouns: "Distributed system design", "Getting started with Kubernetes", "Amazon Web Services (AWS)".

This letter case rule applies only to headings. The title of an external work — a book, film, or similar — is rendered in title case when cited.

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, eg. 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 up to a maximum of level-4 (where the document title in level-1).

Do not set any part of a heading in monospace, bold, or italic. A heading is already visually distinct by its size and weight, and inline formatting on top of that can confuse rendering issues in some cases.

Hedging

State a claim once, with the confidence it actually deserves. Stacked hedges such as "could potentially possibly" or "it might be argued that" dilute a claim past usefulness, and leave the reader unsure whether the author believes it.

Where a fact is uncertain, say what is known and how it is known, or say plainly that it is not yet known. Do not fall back on a vague disclaimer such as "based on available information" or "details are limited," which signals doubt without locating it. Where a fact is likely to change, date it: "as of March 2026," not "at the time of writing."

Hyphenation

Hyphenate a compound modifier that precedes the noun it modifies, when leaving it open could cause the reader to misparse the sentence: "a well-defined interface," "a two-factor login." Do not hyphenate the same compound when it follows the noun it modifies: "the interface is well defined."

Do not hyphenate a compound modifier whose first word is an -ly adverb: "a poorly documented API," not "a poorly-documented API." The adverb can only modify the adjective that follows it, so the hyphen adds nothing.

Do not hyphenate a unit of measure written with a numeral: "32 MB," "10 ms," not "32-MB" or "10-ms," even when the pair is being used as a modifier ("a 32 MB heap").

Inclusive 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.

Instructional steps

Sequence a procedure chronologically, not spatially. Prefer "next, select Save to continue" over "click the Save button below": a spatial reference such as "below," "above," "on the left" assumes a fixed visual layout that a screen-reader user, a voice-interface user, or a reader on a narrow viewport does not share, where content is not read or laid out in the same order it appears to a sighted mouse user. A step written as a position in a sequence ("next," "then," "finally") holds regardless of how the interface is rendered or navigated.

Prefer a device-agnostic action verb over a device-specific one: "select" or "choose" over "click," "tap," or "press"; "view" over "see." A device-specific verb assumes the reader is using a mouse, which excludes keyboard, touch, and assistive-technology interaction, none of which is a "click."

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.

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. Terminate the lead-in sentence with a period, not a colon or dash.

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.

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.

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.

Where nesting is warranted, mark the nested level with an em dash rather than a second round of bullet characters, so the two levels stay visually distinct at a glance:

* Supported runtimes
  — Node.js 20 and later
  — Python 3.11 and later
* Supported operating systems
  — Linux
  — macOS

Convert a bulleted list whose items are each a short term and its definition into an AsciiDoc description list instead of a plain bulleted list, since a description list renders the term and definition with distinct styling that a bulleted list cannot express:

Spellchecking:: The process of checking a document for misspelled words.
Kerning:: The process of adjusting the space between characters in a font.

Numbers

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.

Spell out an ordinal from first through ninth; use figures with the suffix from 10th upward: "the third retry," "the 12th request." Hyphenate a spelled- out fraction used as a modifier ("a two-thirds majority") but not a figure fraction. Write "percentage points," not "percent," when stating the difference between two percentages: "latency dropped 5 percentage points, from 20% to 15%" — "dropped 5 percent" would mean a relative drop to 19%. Write a numeric range with an en dash and no surrounding spaces (10–20).

Order of information

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. Put background, rationale, or philosophy 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."

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>]

The same convention applies inline in prose, not only inside code blocks — for example, a URL containing a variable segment: https://example.com/accounts/<account-id>/. Where the placeholder syntax needs to match a formal grammar rather than this standard’s own convention — for example, a URI Template per RFC 6570, which uses curly braces rather than angle brackets — follow that grammar instead and say so on first use: https://example.com/accounts/{account_id}/ (URI Template).

Do not pin a real version number of a fast-moving tool or runtime (Node.js, npm, TypeScript, and so on) in an illustrative example where the point being made is a policy or a pattern, not a testable version requirement. State the policy in prose instead (eg. "the two most recent maintenance LTS releases") and use placeholder notation for any version numbers in the accompanying example, so the example doesn’t need re-editing every time the ecosystem moves on. This doesn’t apply to a version cited as an actual testable requirement, which must be a real number.

Plain language

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.

Promotional language

Avoid marketing-register words in technical writing, eg. "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, eg. "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."

Exclamation marks are the punctuation form of the same failure.

Quotation marks

Use plain, straight double quotes ("like this") for quoted prose, never AsciiDoc’s curly-quote syntax ( “like this” ) — see TS-28 for that syntax note. Use single quotes only for a quotation nested inside another quotation.

Place a period or comma that ends a quoted phrase inside the closing quotation mark, following American convention: the response returns "not found." not the response returns "not found".. A colon, semicolon, question mark, or exclamation mark goes outside the closing quotation mark unless it is part of the quoted material itself.

Backticks MUST NOT appear inside a quoted string in prose. Quote the phrase or set the term in monospace, never both — pick the one that reflects what the text represents:

✅ "list responses within 300 ms at the 95th percentile"
✅ The `Scenario Outline` keyword.
❌ "the `Scenario Outline` keyword"

This applies to prose only. Backticks inside a code block are untouched by this rule, including where the language being shown uses them as syntax.

References

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".

For essay anthologies, use the editors' names and write "(editor)" or "(editors)" after, eg. "Smith and Jones (editors)".

Omit the year entirely, rather than writing "(n.d.)," when a source doesn’t state one: "Johnson, M. The Future of Learning. Horizon Press." Don’t invent a year either.

Render the title in title case.

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

References sections in the technical standards

The references section at the end of each technical standard is a bibliography, not a plain link list, and it lives in its own partials/NNN/99-references.adoc partial (see the repository’s style guide for the file-layout mechanics). Each entry is one * bullet on a single source line, in this fixed order:

* <author> (<year>). {link-<slug>}[_<title>_].

Entries MUST be listed alphabetically by author surname (or by organization name, where the source has no individual author), so that a growing reference list stays scannable rather than reflecting the order sources were added in. Where two entries share the same author, order them by title.

The URL itself is never inlined here — it’s declared once as a :link-<slug>: attribute and referenced by name. All of a standard’s :link-<slug>: attributes, whether cited in the references list or only in the body, live together in a single alphabetized-by-slug block at the top of the page — see the repository’s style guide for the file-layout mechanics. Where a source has no clear individual author, cite the organization or site as the author, consistent with the press-release and news-story guidance above. An entry cites one work and carries one link; omit the publisher and any annotation — the linked title is enough to identify the source, and a reader who needs more follows the link.

Referring to figures, tables, and examples

Do not refer to a figure, table, or code example by its position on the page ("the table above," "the diagram below"). Position is not stable across formats — a reflowable or narrow-viewport rendering can move a figure to a different position relative to the text that cites it. Refer to it by number or an explicit cross-reference instead: "see the 'Retry backoff' section," or "Table 3 lists the supported operations." Use "preceding" or "following" only where a live cross-reference genuinely isn’t available, since even those describe a position rather than pointing directly at the target.

Give every numbered figure, table, and example a caption in sentence case, with no period at the end, and refer to it specifically in the surrounding prose rather than leaving it to speak for itself — a reader scanning past figures should still get the point from the body text.

Requirements levels

Use the IETF RFC 2119 requirement keywords — MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL — in body prose to express an obligation, a prohibition, or a genuine option. Prefer this over using softer everyday phrasing such as "should probably" or "it’s a good idea to."

Render each keyword in capitals as shown. Do not use the mixed-case spelling — "Must," "should not" — that some style guides prefer.

A document that relies on these keywords MUST state, once, near its start, that they carry the meanings defined in IETF RFC 2119. An example follows.

The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, written in their full uppercase forms, are to be interpreted as described in IETF RFC 2119.

Rhetorical constructions

Do not use "not only…​ but also…​" or "it’s not just X, it’s Y" for rhetorical effect. Reserve these constructions for a genuine contrast the reader needs to see.

Do not pad a list or a sentence out to three items because three sounds complete. Give two items where two are true, and four where four are.

Do not use "from X to Y" to suggest breadth unless X and Y are the real end points of a range that the text actually covers. "From onboarding to offboarding" is fine in a document that covers the whole employee lifecycle. "From data structures to distributed consensus" in a document about one sorting algorithm is padding.

Section endings

End a section on its last concrete fact or on the actual next step. Do not close with a content-free upbeat line such as "the future looks bright" or "exciting times lie ahead."

Do not add a generic closing section such as "Future outlook" or "Challenges and legacy," or a reflexive summary in the form "Despite these challenges, the project continues to…​". These add length without adding information. Name the specific open problems and the specific plans for them, or omit the section.

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 sentence ending with a short, comma-separated list set off 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. Varying sentence length 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.

Text in which every sentence is close to the same length, and every paragraph the same shape, reads as mechanical even when each sentence is individually correct.

A sentence fragment is acceptable as a deliberate device for pace or emphasis, landing a short point after a longer sentence has built up to it: "The request failed. Again." Do not use a fragment where the reader could mistake it for an incomplete sentence rather than a stylistic choice — reserve it for a clause that plainly could not be read any other way.

Significance claims

Show that something matters by stating the fact that makes it matter, not by asserting its importance. Phrases such as "stands as a testament to," "marks a pivotal moment," "underscores the importance of," and "plays a crucial role" claim significance without demonstrating it. State what happened and let the reader judge.

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

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

Specialized referencing conventions

A small set of domains outside general prose citation have their own established referencing conventions. Follow them rather than improvising a technical-documentation equivalent.

  • Latin binomial (scientific) names. Italicize the full genus-species name — Escherichia coli — with the genus capitalized and the species lowercase. After first use, the genus MAY be abbreviated to its initial: E. coli.
  • Classical-music works. Cite a work by its catalog designation where one exists (opus number, or a composer-specific catalog such as BWV for Bach or K. for Mozart) rather than title alone, since many classical works share a generic title: "Beethoven’s Symphony No. 5 in C minor, Op. 67," not just "Beethoven’s Fifth Symphony."
  • Biblical citation. Cite as <Book> <chapter>:<verse> — "John 3:16," or a range as "Romans 8:28-30." Abbreviate the book name only where the document already establishes the abbreviation on first use, following the same first-use rule as any other abbreviation.

Tense

Prefer present tense when describing current system behavior. "The function returns null" reads better 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.

Terminology

Use one term per concept, consistently, throughout a document and ideally across a body of documentation.

Do not vary terminology for the sake of stylistic variety. For example, "endpoint," "route," and "handler" should not be used interchangeably to refer to the same thing. A reader may 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.

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

Watch for words chosen because they sound weighty rather than because they are precise, eg. "delve," "leverage," "foster," "landscape" (used abstractly), "tapestry," "intricate," "crucial," "robust," "seamless." None is forbidden outright, but a document that leans on several of them reads as padded. Rewrite with plainer words.

Prefer a plain "is," "are," or "has" over an inflated substitute such as "serves as," "stands as," "represents," "boasts," or "features." 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."

"That" and "which"

Use "that" to introduce a restrictive clause — one that narrows down which thing is meant, and that the sentence would change meaning without: "the endpoint that returns paginated results." Use "which" to introduce a non-restrictive clause — one that adds incidental information the sentence would still make sense without — set off by a comma: "the endpoint, which was added in v2, returns paginated results." Dropping a restrictive "that" clause changes which endpoint is meant; dropping a non-restrictive "which" clause only removes a side note.

Titles of works

Set the title of a standalone work — a book, a paper, a film, a full publication — in italics: "Designing Data-Intensive Applications." Set the title of a work that is part of a larger publication — an article, a chapter, a blog post, a section — in quotation marks instead: "the article 'Falsehoods Programmers Believe About Time.'" A title within a running-text citation follows this same split, but a title in a reference list entry is always italicized, whatever kind of work it is — see References.

Render the title itself in title case, capitalizing the first and last word and every principal word in between, and lowercasing only articles ("a," "an," "the"), coordinating conjunctions ("and," "but," "or," "nor"), and short prepositions (four letters or fewer, eg. "of," "in," "with") unless one of those starts or ends the title: "Designing Data-Intensive Applications," not "Designing data-intensive applications."

This is the opposite of the sentence-case rule for headings and is a deliberate exception to it. Title case preserves the work’s own conventional presentation, and readers already expect the proper name of a published work to be capitalized this way.

Use the title’s own capitalization as published where it deliberately departs from this pattern (eg. a stylized lowercase title), rather than forcing it into title case.

Tone

Write in a plain, factual register. Technical documentation states facts and lets the reader judge their significance. It does not sell, cheer, or chat.

Trailing participial clauses

Do not end a sentence with an "-ing" clause that restates its point in vaguer terms, eg. "…​, ensuring reliability," "…​, highlighting its flexibility," "…​, reflecting the team’s commitment." If the clause does not add a new, concrete fact, cut it. If it does, consider giving that fact a sentence of its own.

Bad: "The service retries failed requests three times, ensuring reliability."

Good: "The service retries failed requests three times, with a 200ms backoff between attempts."

Units of measure

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.

References