What the work actually is.
WHAT TECHNICAL WRITING IS
Explaining how something works or how to do something, to someone who needs to act on it.
WHAT IT IS NOT
Writing that demonstrates the writer's knowledge Marketing material Prose to be admired
WHY THAT MATTERS
The reader has a task, and everything that does not serve it is an obstacle.
WHAT IT COVERS
User guides and manuals Installation and setup instructions Reference documentation Procedures and work instructions Release notes Help articles and knowledge bases Application programming interface documentation Specifications and requirements
WHAT DETERMINES WHETHER IT SUCCEEDS
Whether the reader completes their task.
WHY THAT IS THE ONLY MEASURE
Documentation that is accurate, complete and unusable has failed.
WHO READS TECHNICAL DOCUMENTATION
People with a problem, in a hurry.
WHAT THAT IMPLIES
They do not read from the beginning They scan for what they need They stop as soon as they think they have it
WHAT TO DESIGN FOR
Scanning and partial reading.
WHAT MAKES DOCUMENTATION FAIL
It assumes knowledge the reader lacks It is out of date It cannot be found It describes the intended behaviour rather than the actual one It is too long to use
WHAT TO TREAT THIS CATEGORY AS
Practical guidance for anyone who must document technical work.
