I work for a company that often requires me to follow other people's procedural documentation for dealing with things like failures of hardware/software, deploying new code, or even installing OS updates. While I could go into length about procedure or process trying to replace common sense, that is a topic for another day. I merely want to highlight how to produce good documentation that is easy to follow. I have often missed a step, or not done something correctly as a result of documentation being hard to follow, especially at 3 o'clock in the morning.
Consider the following example for modifying a database table as part of a code deployment. This is an excerpt from an actual change procedure for code deployment I've had to follow. It was presented exactly as you see it below, sanitized for security reasons obviously.
4. If ammending an existing table:
Take a backup of the database table:
cd /home/user1
mysqldump -uroot -p dbproduct tblextinfo > tblextinfo.sql
(!!!NOTE the use of 'dbproduct' 'tblextinfo' and the file name 'tblextinfo.sql' is an example only!!! --check the file 'database.txt' in the associated ticket for what database and table the alter statement refers to !!NOT all CRs will require a table alteration!!!)
After successful backup:
logon to mysql and run:
USE dbproduct;
ALTER TABLE `dbproduct`.`tblextinfo` MODIFY COLUMN `fldBody` MEDIUMTEXT
DEFAULT NULL;
Now here's my rewritten version which, in my opinion, is much easier to follow.
Ammending an existing table:
- Take a backup of the database table.
(Substitute 'database1' and 'table1' for the actual database and table names which should be in 'database.txt' provided with the request.) - After successful backup, logon to mysql and run:
cd /home/user1
mysqldump -uroot -p database1 table1 > database1.table1.$(date "+%Y%m%d").sql
USE database1;
ALTER TABLE `database1`.`table1` MODIFY COLUMN `fldBody` MEDIUMTEXT DEFAULT NULL;
So what makes it easier to follow?
- Headings that stand out - If your procedure consists on different sections which it should, make sure each section has a heading that stands out to make it easier to find. The person following the document doesn't want to read through the whole thing to find what they're looking for on the last page. This will agitate them and increse the likelyhood of something going wrong.
- Lists - If the procedure requires that that things be done in a particular order, use an ordered (numerical) list. If you need to list devices on which steps need to be carried out, use a bullet point list.
- Fixed width font for commands - Why would you hide commands that need to be run in a sea of instructional text? Make the command stand out, and use fixed width to clearly show that it's a command. Even better, shade the background of the command one shade darker.
- Important info first - Important information relating to a command or the whole process should be provided before the command or the first step of the procedure so that the person running the command(s) or carrying out tasks on a system knows what they are, or is relevant to. We work from the top down, so telling the person carrying out your task that the command is not relevant in case of X after giving the command will result in them running it and only afterwards will they realise that it is not needed. This will often have a negative outcome.
- More should be less - This applies to information and commands. Don't flood the person following your document with largely irrelevant text. Tell them what they need to know and keep it as short and to the point as possible. They probably don't care or need to know about the background or why this is being carried out. Also try to combine commands where ever possible. Instead of having
echo 1 > file.txt
script.sh -i file.txt
cat output.txt | mail admin@example.com
combine the lot
echo 1 > file.txt && script.sh -i file.txt && cat output.txt | mail admin@example.comThe person carrying out the steps is only going to copy and paste the commands anyway, and where output does not need to be specifically monitored it's far easier to run one command than it is to run three.
The only time more is needed is in the event of a command or step producing an undesired result. Where this is a possibility make it clear that this is a possibility before the step and then included a sub-section with information on what to do in the event. Make it a sub-section so that it can easily be ignored when the step succeeds.
