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.
Wrong samples
Right Way
Log on to the database server and get root rights
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
Deploy version 1.4.2 of the Marketplace software on the App servers and save the output
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