Technical Writing for Customers
This week three people need to read about the same change: scanned invoices will now always go to a clerk. Meera has to approve it. Kavitha needs to know whether any data flows change. Farhan's clerks need to know what will appear on their screens. One change, three readers, three different pieces of writing.
The rule
Lead with the conclusion, write for one reader, record what was decided.
- Lead with the conclusion. The first sentence gives the answer, the decision or the request. Background comes after, for those who want it.
- Write for one reader. Meera needs outcome, cost and risk. Kavitha needs systems, data flows and access. Clerks need steps. A document that tries to serve all three serves none of them well.
- Be concrete. "Invoices over ₹5 lakh always go to Meera" beats "high-value transactions are subject to additional review".
- Record what was decided. Decisions made in meetings fade. A short written record keeps the decision and its reasons after people forget, leave or change their minds.
An FDE writes many small documents: a discovery summary, a scope document, architecture notes, weekly updates, a decision log and a runbook. A decision record needs only a few lines:
DECISION 7 · 12 March · Scanned invoices go to clerks
What: scanned photocopies are never approved automatically during the pilot.
Why: on the evaluation set, only 71% of fields on scanned photocopies are read correctly.
Options considered: automatic approval with spot-checks; leaving these carriers out.
Decided by: Meera Iyer, with Farhan Sheikh and the Loomwork FDE.
Revisit: when scanned-invoice accuracy passes 95% on the evaluation set.The shortcut
Apply the first-line test: cover everything below the first sentence. Could the reader act on that sentence alone? If not, rewrite it.
The draft
"Over the past two weeks we have been looking into various aspects of how scanned invoices are processed."
The trap is the warm-up paragraph: context, history and thanks before the point, so a busy reader stops before reaching it.
Drills
Answer fast — trust the rule.
Which opening line works best in an email to Meera?
Which detail belongs in Kavitha's architecture note but not in Meera's summary?
Why keep a decision log?
Which sentence is the most concrete?
Remember
- Lead with the conclusion, write for one reader, record what was decided.
- Shortcut: the first-line test. Could the reader act on the first sentence alone?
- Trap: warm-up paragraphs, and one document trying to serve every reader.