Writing technical documentation
Writing a procedure that can be followed without guessing: the reader, prerequisites before the steps, one action per step, the expected result, the warning before the action and one word per thing.
- 26 cards
- 5 topics
- Free
The outline, topic by topic
Each topic is weighted the way the exam weighs it.
- Concepts
- Questions
- Sort and link
- Scenarios
- Understand
A few cards from the deck
Procedure: what is it?
Show the answer
A text that describes, step by step, how to carry out a specific task.
It must be followable by someone who has never done the task, without guessing: what seems obvious to the author is not so for the reader.
Which of these steps is well written for an administrator?
- Restart the service with the command
sudo systemctl restart nginx. - Afterwards you will have to remember to possibly restart the service if needed.
- The service is restarted, then the configuration is checked.
- Restart the service and check that it is running.
Show the answer
Restart the service with the command
sudo systemctl restart nginx.The right step has a command verb, a single action and the exact command. The first is vague (“possibly”, “if needed”), the second is passive with no actor, the third bundles two actions.
- Restart the service with the command
A step contains … action only, with a verb in the …: “Open the file”.
Show the answer
A step contains one action only, with a verb in the imperative: “Open the file”.
If a step holds two actions, the reader forgets one, and when it fails nobody knows which of the two went wrong.
Prerequisite: what is it?
Show the answer
What you need to have or know before starting: access, rights, software, version, backup.
They go before the first step: discovering at step six that an administrator right was needed forces a restart from scratch.
A colleague follows your restore procedure and overwrites the production database: the warning was written after the step. What fix?
- Put the warning before the step, the backup in prerequisites
- Put the warning in bold and red right after the step
- Add a long paragraph of context before the start of the procedure
- Number the warning as a step of its own, at the end of the procedure
Show the answer
Put the warning before the step, the backup in prerequisites
Bold does not change the reading order: the step is already done when the warning is read. It has to be read before acting, with the backup stated as a prerequisite.