A guide says, ‘Export the file, then check that it worked.’ The reader clicks a button and gets an empty file. Was the selected date range wrong, did a permission fail, or was the export incomplete? A technically accurate sentence can still leave a reader unable to finish the job.
The gold standard of technical writing is clear, accurate, accessible and verifiable information that helps readers complete a task under stated conditions. This guide follows a fictional software-export problem through twenty-three controls, error recovery, API documentation, accessibility and evidence-based user testing.
Quick information: how to recognise usable technical writing
| Document element | What the reader needs | Weak substitute |
|---|---|---|
| Purpose and scope | A defined task, supported product and version | A long list of features |
| Prerequisites | Conditions the reader can check | ‘Make sure everything is ready’ |
| Steps | One action, named location and order | Several hidden decisions in one sentence |
| Expected result | Observable indication of success | ‘Done’ without verification |
| Exception path | Recognisable error and safe next action | ‘Try again’ for every failure |
| Evidence | Tested examples and accountable update process | Polished writing without validation |
Worked rewrite: replace an ambiguous export step
| Version | Instruction | What can be verified |
|---|---|---|
| Weak | Export the report and make sure it worked. | No defined report, period, location or outcome |
| Improved | Select the required report and date range. Confirm export permission. Use the labelled Export control. Locate the saved file and verify its required column headers. | Starting conditions, concrete actions and observable result |
The improved version is still incomplete until it names how a reader identifies empty exports and where to seek support. That is why useful documentation tests both a normal path and at least one relevant failure path. The software, labels and actions are invented teaching examples, not instructions for a specific product.
Worked measurement: 65% versus 90% task completion
| Fictional test | Completed | Total | Completion rate |
|---|---|---|---|
| Before revision | 13 | 20 | 65% |
| After revision | 18 | 20 | 90% |
| Observed difference | +5 | 20 | +25 percentage points |
A rewrite accompanied a 25-percentage-point rise in observed completion. It is not automatically evidence of a causal improvement: participant experience, system versions, task selection and other conditions might differ. Use comparable tests, error logs and qualitative observations before making a strong claim.
23 controls for technical writing
Understand the reader’s task
Chapters 1–6: Technical writing exists to make a task achievable · Find the reader’s actual question · Name the audience and the scope · Separate concepts, procedures and reference facts · Begin with prerequisites that can be checked · Describe the starting state and expected ending state.
Write precise procedures
Chapters 7–12: Write one meaningful action per step · Use interface names and symbols consistently · Give an immediate way to check each important result · Worked example: repair an ambiguous export instruction · Diagnose the mistake instead of repeating the same instruction · An error code needs explanation and a safe next step.
Document technical behaviour and change
Chapters 13–16: Treat command examples as executable artifacts · State the contract of an API, not merely its endpoint · Do not confuse a generated API specification with task guidance · Keep documentation aligned with the product lifecycle.
Test accessibility and correctness
Chapters 17–21: Test documentation with real tasks · Write for screen readers and resizing, not only screenshots · Prepare technical language for localisation · Present numerical values with units and assumptions · Safety language must be unambiguous and within scope.
Maintain and teach
Chapters 22–23: Audit ownership, correction and release evidence · Connect writing to teaching and durable knowledge.
- Technical writing exists to make a task achievable
- Find the reader’s actual question
- Name the audience and the scope
- Separate concepts, procedures and reference facts
- Begin with prerequisites that can be checked
- Describe the starting state and expected ending state
- Write one meaningful action per step
- Use interface names and symbols consistently
- Give an immediate way to check each important result
- Worked example: repair an ambiguous export instruction
- Diagnose the mistake instead of repeating the same instruction
- An error code needs explanation and a safe next step
- Treat command examples as executable artifacts
- State the contract of an API, not merely its endpoint
- Do not confuse a generated API specification with task guidance
- Keep documentation aligned with the product lifecycle
- Test documentation with real tasks
- Write for screen readers and resizing, not only screenshots
- Prepare technical language for localisation
- Present numerical values with units and assumptions
- Safety language must be unambiguous and within scope
- Audit ownership, correction and release evidence
- Connect writing to teaching and durable knowledge
CONTROL 1 OF 23 · All controls
1. Technical writing exists to make a task achievable
Technical writing explains products, processes, data and decisions so a real reader can understand or perform something correctly. A manual, API guide, maintenance instruction or research method may be technically accurate but fail because the necessary action is hidden or an important precondition is missing. The gold standard is writing that is correct, usable, safely bounded and verifiable by someone other than its author.
A clear document distinguishes what a system does, what it does not do, what the reader needs beforehand and which outcomes show success. The writer must know the subject deeply enough to detect ambiguities, yet explain it without making the learner feel incompetent. Documentation concerns the broader record; Communication concerns information exchange. Technical writing specialises in actionable explanations and reference material whose precision matters.
CONTROL 2 OF 23 · All controls
2. Find the reader’s actual question
Start with a user need, not with a tour of every feature available. A person opening a software export guide may simply need to save a valid file, check its location and avoid losing an earlier version. A chronological history of the application’s interface will not help them finish that task.
Research where readers get stuck through support requests, observed sessions, search queries and interviews where appropriate. Ask what they already know, which assumptions are safe and what would count as completion. Then design the document around the task. GOV.UK guidance on documenting APIs explicitly recommends task-based instructions informed by user research rather than treating generated reference specifications as sufficient documentation.
CONTROL 3 OF 23 · All controls
3. Name the audience and the scope
Technical documents may be read by first-time users, specialists, auditors or people returning after months away. A procedure written for a trained engineer may omit knowledge that a student or customer does not have. Conversely, explaining elementary terms on every reference page can obstruct an expert looking for one parameter.
State the required level, supported product version, platform and intended setting. Do not invent a general reader if the process requires licensed or qualified supervision. Use links to background material when readers need a concept before proceeding. Conditions should be visible at the point where they change an instruction, not tucked away in an unrelated appendix.
CONTROL 4 OF 23 · All controls
4. Separate concepts, procedures and reference facts
A conceptual explanation answers why something works. A procedure shows how to accomplish one specific task. Reference documentation records commands, fields, accepted values and system behaviour. These forms serve different navigation needs even when they describe the same system.
For a fictional data export feature, a concept page explains what a CSV file contains; a task page explains how to export it; a reference page lists the file columns and encoding. Trying to combine all three in a long unstructured paragraph increases the chance that readers miss a critical step. Cross-link the forms and keep each promise narrow.
CONTROL 5 OF 23 · All controls
5. Begin with prerequisites that can be checked
Instructions often fail because they silently assume permissions, installed components, service availability or a particular starting state. A prerequisite is useful only when a reader can establish whether it is satisfied. ‘Make sure your system is ready’ gives no practical way to know.
Prefer clear prerequisites such as ‘Use a test account with export permission’, ‘Select a record that contains sample data’ and ‘Confirm that the chosen destination folder is writable’. Define safe sample data rather than encouraging people to experiment on production records. When steps differ by platform or access level, make those conditions explicit before asking the reader to act.
CONTROL 6 OF 23 · All controls
6. Describe the starting state and expected ending state
A procedure operates on a system that has a state. If the reader starts in the wrong state, every following instruction may be confusing even when individually correct. Identify where the user begins and which visible information establishes completion.
For example, a data-export tutorial can begin at an account’s Reports page with a selected date range. It should end when a file exists in the chosen folder and the reader has verified its expected column headers. Clicking Export is an action; obtaining the correct output is the outcome. Do not call the job complete merely because a button was pressed.
CONTROL 7 OF 23 · All controls
7. Write one meaningful action per step
Procedure steps should follow the order in which the reader must act. Write with precise verbs and identify the location before the action when necessary. An instruction such as ‘configure the service and publish it once it is tested’ contains several decisions, possible failures and outcomes and is too vague to be reproducible.
Split actions logically: select the configuration, save it, test the result, inspect the response and only then release a change under the approved process. Avoid unnecessary interruptions between steps. The Google developer documentation procedures guide and Microsoft’s procedure-writing guidance emphasise scannable, sequential actions.
CONTROL 8 OF 23 · All controls
8. Use interface names and symbols consistently
If a button is labelled ‘Download report’, the instruction should use that label rather than ‘click the blue arrow’ or ‘press the download thing’. Colour, icon position and shape can change across themes or interfaces. Readers using assistive technology may not access the same visual cue.
Define field labels and their required format. Keep the same term for the same concept throughout the documentation. A source value named ‘account number’ should not unexpectedly become ‘customer ID’ unless the text explains a real difference. Terminology consistency is also essential for translation, search and support handovers.
CONTROL 9 OF 23 · All controls
9. Give an immediate way to check each important result
Readers should not have to complete eight steps before discovering that step two failed. A well-chosen expected result can confirm the process while the context is fresh. It may be a file on disk, a status label, an acknowledgement code or a consistent value in a sample response.
Avoid presenting exact messages as universal unless the interface version guarantees them. When text varies with user settings or locale, describe the stable state instead. A troubleshooting guide should distinguish the action, observed response and correct outcome. A screenshot can help locate an element but cannot replace a textual explanation of meaning.
CONTROL 10 OF 23 · All controls
10. Worked example: repair an ambiguous export instruction
A weak fictional instruction says ‘Export the report and check it worked.’ A stronger version names the selected report and period, confirms the export role, instructs the reader to use the labelled Export control, identifies where the file is saved and explains how to inspect the headers. The improved version makes success independently visible.
The writer should also ask what happens if the button is unavailable, the file is empty or the session times out. Each case needs an appropriately scoped route to investigate. The task must not encourage readers to bypass permissions or expose private production data. This is an invented documentation scenario, not a claim about a particular software product.
CONTROL 11 OF 23 · All controls
11. Diagnose the mistake instead of repeating the same instruction
A failed procedure does not always mean that a reader ignored it. The system might be in another state, a prerequisite may be missing, a term may be ambiguous or the instruction might refer to an old interface. A strong troubleshooting document starts with the observed problem and checks the conditions that distinguish possible causes.
If an export produces an empty file, review the selected date range, available records, permissions and export status before telling readers to ‘try again’. An unbounded retry can waste time or create duplicate output. Present a small decision sequence with outcomes and escalation criteria. Add an alternate route when the ordinary one is inapplicable, not merely a reassuring paragraph.
CONTROL 12 OF 23 · All controls
12. An error code needs explanation and a safe next step
Error messages provide evidence only when readers know the system and response context. An HTTP 429 response, for instance, normally concerns rate limiting; a 403 response indicates a permission-related refusal under the relevant API semantics. Neither should be described as a universal invitation to repeat the request immediately.
Documentation should distinguish code meaning, likely causes, retry policy, safe handling of repeated operations and where to obtain support. If the service provides a Retry-After header, explain when it is relevant according to the actual API contract. Do not instruct users to disable security checks simply to make a sample request pass. The GOV.UK API documentation guidance includes rate-limit, timeout, version and support information.
CONTROL 13 OF 23 · All controls
13. Treat command examples as executable artifacts
A code or command example can copy dangerous habits if it contains hard-coded secrets, assumptions about privileges or a destructive command disguised as a demonstration. Use disposable sample accounts and a suitable test environment. Distinguish placeholders visually and describe what must be substituted before execution.
Test a sample against the stated software and version. Its syntax, output format, file path and dependencies should agree with the prose. If the code was simplified by removing important handling, label what is omitted and why. A beautifully formatted sample that cannot run in the intended environment is not reliable technical writing.
CONTROL 14 OF 23 · All controls
14. State the contract of an API, not merely its endpoint
An API reference must describe methods, authentication, parameters, types, response fields, error conditions, limits and version behaviour that users need for integration. An endpoint URL alone cannot tell a developer which request is valid or whether repeating it changes state.
In a fictional interface, version 1.2 might return a field named expiry_date while version 1.3 replaces it with expires_at using an explicitly defined timestamp format. A client written for the older field may fail despite a successful HTTP status. The names and versions are invented to illustrate compatibility. Good release documentation distinguishes what changed, migration steps and which versions remain supported.
CONTROL 15 OF 23 · All controls
15. Do not confuse a generated API specification with task guidance
A machine-readable specification can be an excellent source of truth for endpoint signatures, but users may still need to understand workflow order, account permissions, business rules and how to recover from partial completion. The sequence matters when one operation must precede another.
A task page should guide the reader through a meaningful end-to-end scenario with verified example inputs and outputs. Link to the reference details instead of copying them into every page. If the generated specification and maintained prose disagree, investigate the source and publish a correction rather than quietly selecting whichever description appears more favourable.
CONTROL 16 OF 23 · All controls
16. Keep documentation aligned with the product lifecycle
Technical systems change continuously. A screen label, command option or default value may become invalid after a release. Content owners need a way to learn about those changes before users encounter them. Version numbers, publication dates and planned review dates should be meaningful fields rather than decorative metadata.
Build documentation checks into change management where possible. For example, a software pull request changing a parameter should trigger review of its reference page and affected procedures. Historical guidance may still be useful for supported older releases, but the version boundary must be explicit. Systems Engineering offers a related framework for traceability between requirements and evidence.
CONTROL 17 OF 23 · All controls
17. Test documentation with real tasks
Editing for grammar cannot establish that instructions are usable. Ask representative readers to complete a task using only the document under controlled, appropriate conditions. Observe whether they can locate prerequisites, execute steps, recognise success and resolve a common error without undisclosed help.
A fictional evaluation might show 13 of 20 participants completing an export task before a rewrite and 18 of 20 in a second test afterward. The observed completion rates are 65% and 90%, a 25-percentage-point difference. But if the participants, software, task or other conditions differed, this alone cannot prove the rewrite caused the improvement. The counts and design are illustrative rather than empirical benchmarks.
CONTROL 18 OF 23 · All controls
18. Write for screen readers and resizing, not only screenshots
Accessible documentation uses meaningful headings, descriptive links, readable tables, navigable procedures and text explanations for non-text information. A coloured diagram alone should not contain essential data that cannot be obtained in another form. Keyboard access and coherent reading order matter just as much as visual aesthetics.
The Google accessibility guidance for documentation describes these practices, while the W3C guidance on descriptive headings and labels explains their importance. Test the actual page at enlarged text and with assistive technologies where appropriate. A passing colour contrast check does not establish full accessibility.
CONTROL 19 OF 23 · All controls
19. Prepare technical language for localisation
Technical writing may be translated into languages with different word lengths, grammatical structures, punctuation and conventions. Ambiguous phrases, inconsistent terms and unexplained cultural references increase error risk. A field format such as 2026-10-24 must be described as a precise date format rather than left to local assumptions.
Maintain a glossary and stable names for critical features. Keep parameters, units and code tokens distinct from translatable explanatory text. Review translated instructions with competent language and subject specialists. The Microsoft guidance for global technical writing explains why consistent terminology and straightforward structure improve translation quality.
CONTROL 20 OF 23 · All controls
20. Present numerical values with units and assumptions
Technical writing often communicates temperatures, loads, rates, percentages, money, dates and coordinate values. A naked value can be dangerously ambiguous. State what is measured, its unit, tolerance, conditions and source. Differentiate a recommended setting, a measured reading and a fictional example.
A guide that says ‘wait 30’ has failed even before the reader decides whether it means seconds or minutes. A chart that reports an average without the sample size or time period may invite overconfidence. For education, insist that the learner identify the quantity and the correct operation before calculating an answer. Information Literacy and Evidence-Based Thinking help connect the numbers to valid interpretations.
CONTROL 21 OF 23 · All controls
21. Safety language must be unambiguous and within scope
Some instructions involve electricity, chemicals, medical devices, transport systems or other potentially hazardous contexts. Writers should work with qualified subject experts and applicable requirements rather than inventing safety steps from a familiar-looking template. Critical warnings should be placed near the relevant task and distinguish the hazard from the required protective action.
A manual cannot substitute for professional competence or legally mandated training. Never hide an exception in small type or describe a serious risk as something users can simply ignore. The purpose of good writing is to make the correct safe process understandable and to identify when the reader should stop and obtain appropriate assistance.
CONTROL 22 OF 23 · All controls
22. Audit ownership, correction and release evidence
A technically valid document needs an accountable owner, source references, test evidence, supported versions and an update process. Report broken links, inconsistent commands and user confusion as defects that can be corrected. The history should show what changed and when, without silently erasing earlier limitations that explain support cases.
For a release audit, check every action label, prerequisite, sample output, linked reference and expected result against the actual supported product. Assign reviewers for technical content, accessibility and user tasks. Keep source material that supports important facts. A page is not complete because its copy was approved; it is complete when the intended reader can use it under the stated conditions.
CONTROL 23 OF 23 · All controls
23. Connect writing to teaching and durable knowledge
Technical writing teaches a reader how to make an informed move: what to do, why it is appropriate, how to check the result and what changes when conditions differ. That same reasoning builds strong learners. An educator describing a worked Mathematics solution and a software writer explaining an API share the need for clear assumptions and verification, though their subject matter differs.
The immutable Secondary 1 Mathematics Tutor Clementi Small Groups Tutorials page remains the teaching reference: identify the misconception, model each step and transfer understanding. Continue through Literacy, School Writing Instruction, Teaching Information Design and Education to connect practical documents with lifelong learning.
Operational documentation audit
| Reviewer concern | Evidence to inspect | Typical defect |
|---|---|---|
| Task and audience | User need, actual entry point, named outcome | Feature brochure posing as instructions |
| Technical correctness | Product and API version, tested commands | Outdated parameter or unverified sample |
| Recovery | Expected errors, limits and support path | Unsafe blanket retry advice |
| Access | Heading order, keyboard, screen reader, text alternatives | Screenshot-only explanation |
| Localisation | Stable terms, locale handling and formats | Ambiguous dates or renamed fields |
| Maintenance | Owner, revision log, release-triggered checks | Correctness expires after the next release |
Frequently asked questions
What is technical writing?
Writing and maintaining documents that help readers understand a technical system, perform a task, verify results or interpret precise reference information.
Is technical writing the same as documentation?
Technical writing is a specialised practice within broader documentation and communication work, particularly around actionable instructions and precise reference contracts.
How is a procedure different from a reference page?
A procedure guides a specific task through actions and outcomes; a reference page defines fields, commands, limits and behaviour for lookup.
What makes an instruction testable?
A reader can establish prerequisites, perform unambiguous actions and observe a defined outcome under the stated conditions.
Should every technical page have screenshots?
No. Use them when they provide useful context, keep them current and offer accessible text. Images cannot replace the semantic steps.
How do you know whether a rewrite is better?
Test comparable tasks with representative readers; measure outcomes and errors, then assess uncertainty and other changed conditions.
What is the most damaging documentation mistake?
Presenting the author’s assumed successful path as universally valid while hiding prerequisites, errors, versions or recovery routes.
Why should software changes update documentation?
Commands, interfaces and responses may change. Without coordinated updates, previously accurate instructions become unsafe or misleading.
Authoritative editorial and accessibility references
The Google developer documentation style guide and its procedures guidance explain clear technical writing and task steps. GOV.UK: Documenting APIs covers user needs, task-based pages, reference sections, errors, rate limiting, support and versioning. Google accessible documentation guidance, W3C headings and labels guidance and Microsoft global writing guidance inform accessible and localisable presentation. No organisation is claimed to endorse this eduKate article.
The export workflow, invented API versions, completion data and instructional examples are original explanatory scenarios, not live product instructions or validated experimental findings. For safety-critical procedures, applicable standards and competent professional review must be obtained.
Connected Gold Standard subject roots
Documentation · Communication · Typography · Literacy · Information Literacy · Websites · Systems Engineering · Science Communication · Education · School Writing Instruction · Teaching Information Design · Evidence-Based Thinking