What good technical prose is for
Technical writing exists so that a specific person can do something: make a decision, repeat a procedure, check a result, or carry on a project you handed over. It is judged by whether that reader gets what they need quickly and without misreading it. Style, vocabulary and cleverness matter far less than that.
This article covers the principles that apply to almost any technical document, from a short note to a long report. Specific formats such as the formal report, the slide deck or the email each have their own conventions; here the focus is on the prose underneath all of them.
Start with the reader and the purpose
Before drafting, answer two questions in a sentence or two each. Who will read this, and what will they do with it? A manager deciding whether to fund a change needs the conclusion and the cost of the options. A colleague repeating your test needs the exact steps and settings. The same facts, written for these two readers, will be arranged differently.
It helps to write down what the reader already knows. If you are unsure, assume an intelligent reader from a neighbouring field: someone who is capable but does not share your project’s shorthand. Documents written this way tend to age better, because the person reading them in two years may be you, having forgotten the details.
Put the important point first
Many technical documents are written in the order the work happened: background, attempts, dead ends, and finally the answer. Readers usually want the reverse. Lead with the conclusion or the request, then give the support in order of importance.
A simple test is to cover everything except the first paragraph. Could a busy reader act on it? If not, move the key result or recommendation up. Details that only a few readers need can go later, or into an appendix.
Structure the document so it can be scanned
Most people do not read technical documents from start to finish on a first pass. They look for the part they need. Help them with:
- Descriptive headings that say what the section contains, rather than vague labels.
- Short paragraphs that each make one point, usually beginning with a sentence that states it.
- Lists for steps or parallel items, and tables for comparisons across the same attributes.
- Consistent ordering, so that similar sections look alike.
Use lists only when the content is genuinely list-shaped. A chain of reasoning is better as connected sentences, because a list hides how one point leads to the next.
Choose plain, precise words
Plain and precise are compatible goals. Prefer the shorter, more familiar word when it means the same thing: “use” rather than “utilise”, “start” rather than “commence”. Keep sentences to one main idea where you can, and put the subject and verb near the front.
Precision is a different matter. A technical term should be used exactly, and defined at first use if some readers may not know it. Pick one term for one thing and stick with it. If you call a part a “bracket” in one paragraph and a “mount” in the next, a careful reader will wonder whether you mean two parts. The same goes for numbers: give units every time, and state how a value was obtained when it matters. The related habits of replacing jargon and trimming long sentences are covered in more depth under plain language, and the units side of precision is worth reviewing alongside significant figures and rounding.
Be careful with vague quantifiers such as “significant”, “small” or “fast”. If you have a figure, give it; if you do not, say so. Also separate what you observed from what you infer. “The signal dropped to 2 V” is an observation; “the sensor failed” is an interpretation, and should be labelled as one.
Handle figures and tables deliberately
A figure should earn its place by making something easier to see than words would. Each one needs a number, a caption that says what to notice, labelled axes with units, and a mention in the text before it appears. A reader should be able to understand the figure and its caption without hunting through the body, though the body should still say what the figure shows.
Keep figures simple. Remove decoration, avoid relying on colour alone to distinguish lines, and make sure text is readable at the size it will be printed or displayed. Choosing the right chart type is a design question of its own, discussed under data visualization. For tables, align numbers consistently, give units in the column headings, and avoid more columns than the reader can compare.
Draft first, then edit in passes
Writing and editing are different activities, and mixing them slows both. Get a rough draft down first, even if it is untidy, then revise in separate passes, each with a single focus:
- Content. Is anything missing, wrong or unnecessary? Does the order serve the reader?
- Structure. Do the headings and paragraph openings tell the story on their own?
- Sentences. Cut padding, split overlong sentences, and turn passive constructions into active ones where the actor matters.
- Details. Check units, figure numbers, names, references and spelling.
Leaving the draft alone for a day, when the schedule allows, makes problems easier to spot. Reading it aloud also helps, since awkward sentences are harder to ignore when spoken. Whenever possible, ask a colleague outside your immediate project to read it and tell you where they got lost. Their confusion is useful data about the document, not a judgment of you.
Common habits worth breaking
- Starting with a long history of the project before saying what the document is for.
- Using “it was found that” and similar constructions that hide who did what.
- Switching tense or terminology without a reason.
- Burying a caveat that changes the meaning of the result.
- Treating the first draft as final because the deadline is close.
Where to go next
Good technical prose is a skill that improves with deliberate practice. A useful routine is to keep a short checklist of the mistakes you personally make most often, and run through it before sending anything. Over time the list shrinks. Pair that with good record keeping, as in technical notebooks, and you will have the raw material to write accurate documents quickly. Conventions differ between organisations, journals and countries, so where a style guide or template applies to your work, follow it.