Technical Writing Fundamentals

updated 2026-04-08 Technical Writing technical writing communication documentation
Contents
  1. Audience Analysis
  2. Structure Before Prose
  3. Clarity Principles
  4. Writing for Skimmability
  5. Mathematical Writing

Technical writing is the practice of producing clear, accurate, and useful documentation for technical subjects and technical audiences. It differs from other writing in its emphasis on utility over aesthetics, and in the domain knowledge required to write accurately about complex subjects.

Audience Analysis

Every piece of technical writing implicitly answers: what does this reader need to accomplish, and what do they already know?

  • Novice readers need conceptual scaffolding before details; analogies and definitions matter
  • Expert readers are impatient with explanation of things they know; precision is valued
  • Mixed audiences require layered structure: summaries at the top, depth below

Misjudging the audience is the most common source of unsuccessful technical writing. Writing for a reader who knows more than you assume produces condescension; writing for a reader who knows less produces impenetrable prose.

Structure Before Prose

Experienced technical writers plan structure before writing sentences. A document that is hard to outline is not ready to be written.

A useful general structure:

  1. Purpose — what this document covers and for whom
  2. Prerequisites — what the reader needs to already know
  3. Core content — the substance, ordered logically (not chronologically)
  4. Examples — concrete instances of abstract claims
  5. Reference — exhaustive detail the reader need not read linearly

Clarity Principles

Use the active voice. Passive constructions obscure agency and lengthen sentences.

Passive: "The matrix is diagonalised by multiplying on the left by $P^{-1}$." Active: "Multiply on the left by $P^{-1}$ to diagonalise the matrix."

Prefer concrete to abstract. Abstract claims are harder to evaluate and remember.

Abstract: "The system exhibits degraded performance under high load." Concrete: "Latency increases from 40 ms to 800 ms when concurrent requests exceed 500."

One idea per sentence. Long sentences with multiple subordinate clauses are harder to parse and more likely to contain logical errors.

Define terms at first use. Do not assume the reader shares your vocabulary, even if they share your field.

Writing for Skimmability

Technical documents are rarely read linearly. Readers locate the section relevant to their current question and read from there. Good technical writing supports this:

  • Use headings that describe content ("Configuring the retry interval" not "Configuration")
  • Use bullet lists for parallel items; avoid bullets for flowing argument
  • Put the most important information first within each section (inverted pyramid)
  • Use tables and code blocks rather than describing structured data in prose

Mathematical Writing

When integrating mathematical notation into prose:

  • Introduce notation before using it; never let a symbol appear without definition
  • Distinguish between the mathematical object ($f$) and what it represents ("the loss function $f$")
  • Write equations that can be read aloud as English sentences
  • Follow each non-trivial equation with a sentence explaining what it means or implies
  • Punctuate equations as part of the sentence that introduces them