Writing for technical readers

Why it matters

Technical work produces a lot of writing: bug reports, lab notes, test results, design notes, incident summaries, safety notices. The people who read them are usually busy, often switching between tasks, and sometimes reading in their second language. If they misread your text, the cost can be real: a wrong setting on a machine, a bug fixed in the wrong place, a sample run with the wrong method.

Plain language is not "dumbing down". It is writing that your intended reader can find, understand and act on the first time they read it. Experts prefer it too, because it saves them time.

Know your reader first

Before you write, answer three questions:

1. Who will read this? A teammate who knows the system, a manager who needs a decision, a customer who has never seen your code?
2. What do they already know? This decides which terms you must define.
3. What should they do after reading? Approve something, fix something, follow a procedure, or just stay informed?

The same facts can need very different text. A teammate wants the error message and the commit hash. A manager wants the impact and the decision you need from them.

Seven plain-language rules

1. Put the main point first. State the conclusion or the request, then the details.
2. Use short sentences. Aim for an average of 15–20 words. One idea per sentence.
3. Use the active voice. "The script deletes old logs" is clearer than "Old logs are deleted by the script". The active voice tells the reader who does what.
4. Choose common words. "Use" instead of "utilize", "start" instead of "commence", "about" instead of "approximately".
5. Define terms and acronyms once. "Limit of detection (LOD)" the first time, then "LOD".
6. Be specific. Replace "a while", "a lot" and "soon" with numbers, units and dates.
7. Use structure. Headings, short paragraphs, bullet lists for items and numbered lists for sequences. Readers scan before they read.

Worked example 1: an engineering update

Before:

It has been determined that, due to the fact that a significant number
of the sensor readings were found to be anomalous during the period of
the testing that was conducted last week, the utilization of the
current calibration values should be discontinued until such time as
a re-evaluation can be performed.

That is one sentence of 52 words, written in the passive voice, and it never says who should do what. After:

Stop using the current calibration values for the line 3 pressure
sensors. In last week's test, 41 of 200 readings (about 20%) were
outside the expected range. Maria will recalibrate the sensors by
Friday. Until then, use the backup values in calibration-v6.csv.

Four short sentences. The reader knows what to stop, why, who is fixing it, by when, and what to do in the meantime.

Worked example 2: a bug report

Before:

The app is broken when you try to log in sometimes.

After:

Login fails with "Error 500" for accounts with a plus sign in the
email address (for example, sam+test@example.com).

Steps to reproduce:
1. Go to /login.
2. Enter sam+test@example.com and the correct password.
3. Click "Log in".

Expected: you reach the dashboard.
Actual: a blank page with "Error 500".
Happens every time on version 2.4.1, Chrome and Firefox.

The second report can be fixed. The first one starts a conversation.

Numbers, units and precision

Technical readers act on numbers, so be careful with them:

• Always give units: "4.2 mL", "250 ms", "3 kN".
• Keep the number of significant figures honest. Do not write 12.3456 V if your meter reads to 0.1 V.
• Write dates in a format nobody can misread across countries, such as 2026-03-04 or "4 March 2026".
• Say which version, batch, build or instrument you mean.

Common mistakes

• Writing for yourself. Notes that make sense to you today may mean nothing to a colleague, or to you in six months.
• Hiding the point after a long background section.
• Undefined jargon and acronyms, especially team-specific ones.
• Long, nested sentences with "which", "that" and "due to the fact that" stacked together.
• Vague words like "fast", "large", "recently" and "some issues".

A quick self-test: read your text out loud. Where you run out of breath, split the sentence. Where you stumble, use a simpler word.

Quick recap

• Decide who the reader is and what they need to do.
• Main point first, short sentences, active voice, common words.
• Define terms once; give numbers with units, versions and dates.
• Use headings and lists so the text can be scanned.

Try it

Open the Do tab. You will take a dense paragraph and rewrite it using the plain-language rules, then check your version against them.