Prerequisites and assumed knowledge
Write for the intended user, not for an imagined average user. State prerequisites when missing them would stop someone following the document: required product versions, permissions or account roles, installed plugins, existing configuration, access to a server or integration, or knowledge of a specific concept.
Do not force users to research basic missing information before they can even begin. If a short explanation unblocks them, include it. If the prerequisite needs substantial teaching, summarise it and link to dedicated material.
Keep introductions short
Most how-to guides should open with one short paragraph covering what the guide covers, what the user will achieve, and any critical condition affecting whether it applies. Long introductions delay the first useful action.
Voice and tense
Second person, present tense, active voice. “Select Save”, not “the Save button should be selected”. Aim for the plainest wording that stays precise, and where the two conflict, precision wins.
Headings and scanability
A user scanning the page should be able to identify:
- Where the main procedure begins
- Where optional paths appear
- Where warnings apply
- Where troubleshooting starts
- Where related information can be found
Headings do not need one grammatical pattern. Use topic-based or action-based wording depending on which is clearer. A technically complete document that is difficult to scan is not ready to publish.
Separate optional paths clearly
Do not bury optional workflows inside the main sequence. Keep the core path easy to follow, label optional branches, and explain when each applies. Platform-specific instructions can stay in one guide when clear branching keeps it understandable.
Accessibility
Every screenshot needs alt text describing what the user should see, not the word “screenshot”. Never rely on colour alone to carry a step or a warning. Headings must nest in order, because a reader using a screen reader navigates by them.
Localisation
Where documentation will be translated, avoid idiom, keep sentences short, and never embed text in an image.
Keep terminology consistent
Use one clear term consistently across a documentation set. Where the product interface itself is inconsistent, choose a preferred term for the documentation, and name the interface label explicitly when the user still needs to recognise it. Do not silently rename controls in a way that makes them harder to find.
