I love documentation, so long as it is clear, and most importantly, it gives useful examples on how the procedure can be used immediately without too much effort. I don’t like hard, I like easy, thats why we document right! What I don’t like is documentation that causes me to get lost as I start reading it. Once that happens, I get frustrated and move on to seek out better documentation. What causes people to get lost? In my opinion, I believe it is lack of planning on behalf of the individual writing the documentation, coupled with a whole ton of assumptions and not knowing your audience. I hate assumptions when reading procedures.
People who write procedures, in my opinion, must write it as if the reader is a complete newbie. By doing this you level set all your readers. The more advanced reader can just skip to the juicy bits they are more interested in without reading all the background and prerequisites. Explanations, these I love also. If your going to show a command line command, then explain what it is doing. This way you are giving your reader the opportunity to really understand what is going on with all the switches and options used in the command. On that note, give some actual real world usage of the procedure, don’t leave the fella hanging.
So, what makes up a good procedure? What makes it so complete and fool proof? Lets take a stab.
1. Purpose – Describe the purpose of the procedure.
2. Why? Why are we doing this and what are the benefits.
3. Prerequisites & Environment – Tell the reader what ALL the prerequisites are for this procedure and what your environment looks like so they can replicate it.
4. The Procedure – Here is where we commence the actual procedure walking the reader through the steps.
5. Explanations – Provide explanations along the way with screen shots (really good screen shots). During the procedure give detailed explanations of what you are doing.
6. References – Provide links to other web pages topic related. Providing links to additional documentation or other posts discussing the topic gives the reader opportunity to see how other folks are dealing with it or what they know about the subject.
7. Use Cases – How else can I use this? Give additional example(s) of how this procedure can be used. This gets the reader thinking on how they might use the procedure in their environment.
8. Finally, after all of the above is accomplished, the reader leaves with a sense of empowerment and new knowledge to use and share with his peers.
This, I believe, makes up a good template for creating procedures that are well documented and can be repeated by any analyst. If you fail at this, then apply the deming cycle to correct it.
In my next post I will post an empty template to illustrate the above. Beyond that, I will start posting procedures that I have created due to a need and use quite often
Mr. Orinoco
No comments:
Post a Comment