A document is ready when it is accurate, current, focused, easy to scan, appropriate for its audience and sensibly placed in the wider set. Technical correctness alone is not enough: users must also be able to find the information, recognise that it applies to them, and follow it successfully.
The decision process
Used for new documentation, major updates and audits.
- Identify the user intent. Learn, complete a task, look something up, or understand.
- Check what already exists. Overlap, outdated guidance, related pages.
- Decide whether a new page is needed.
- Choose the primary documentation type.
- Check the scope. One primary job, or secondary purposes to separate.
- Check usability. Can the intended user tell the page applies to them?
- Verify the content. Test where possible, flag what is unconfirmed.
- Check wider impact. Related pages, screenshots, terminology, links.
- Check for duplication.
- Apply the publication gate.
The gate
Before publication, every one of these is a yes.
- Does the page serve a clear user need?
- Is it the right documentation type for that need?
- Can the intended user follow it without additional research?
- Is the content accurate and current?
- Is the page easy to scan and navigate?
- Has unnecessary duplication been removed?
- Are terminology and screenshots current?
- Have technical claims been verified where reasonably possible?
- Have related documents been checked for impact?
- Is this the clearest place for this information to live?
