During Procedures, Changes, Documentation, SOPs and similar stuff (from now on refered to as "description"), I use a lot of descriptions that need to be followed by users, developers or sysadmins (from now on refered to as "implementor").
The one thing all there descriptions should have it common is:
- Giving the person the needed tools/guides to get from A to B
- Being clear and straight in all parts
- Not being aubigously, as this will lead to doubt/wrong implementation/ - hence errors
A lot of people write Procedures, Changes, Documentation, SOPs from either
- Their own perspective and knowledge level
- An expection of the implementor knowledge level
which is the most common mistanke to make - relative to the target audience.
As soon as the implementor reads the description, the path to misunderstading and doubt starts, typically because of a lower knowledge level, missing informations and faulte expectations from the authors side.
As always, the is a target audience and the writer can definitily have an assumption and expectation towards the implementers skills and knowlegde level.
For Sysadmins writing SOPs to sysadmins, You must expect that the Sysadmin to carry out the SOP, knows how to logon to a server.
But for Sysadmins writing guides or manualt to end users or superusers, this cant be expected, and the logon procedure has to be explained.
Its better to pin out the details that at first looks stupid or tedious - than making the mistake of not doing it - its virtually impossible to do it to well (respecting and thinking of the target audience)
Wrong samples
Right Way
Log on to the database server and sudo to root
Log on to the database server
ssh db01.mydomain.dk
After login, get root rights:
sudo -s
Run the sql file update.sql on the Market database
Run the attached sql file update.sql on the Market database:
mysql -u marketuser -p market < update.sql
This must not give any errors, output should be like:
5 rows updated sucessfully
Deploy version 1.4.2 of the Marketplace software on the App servers and save the output
Check the output log for errors
Login to each App server (app01.market.mydomain.dk and app02.market.mydomain.dk) and do
sudo -s deploy.sh --version 1.4.2 --summarize > /tmp/deploy.txt
examine if any errors occoured:
cat /tmp/deploy.txt | grep error