Documentation is hard. Really hard. Context matters.

Listen to this article:

Have you ever been responsible for creating step-by-step instructions for a repeatable process?

Have you ever been the recipient of a support call regarding a process you are intimately familiar with?

So intimate that you were the one that created the step-by-step, heavily detailed instructions including screenshots?

The same instructions that apparently only one in thirty-seven can use to properly complete the process – while the other 36 stumble on the most seemingly ridiculous step?

Still today in Information Technology, Systems Administration, or DevOps (whatever you want to call it) this scenario plays out all too often.

The following video is a hilarious demonstration on how all-too-often operators and developers create Standard Operating Procedures (SOPs) equipt with 100% of the context.

The video, for the TL;DW crowd, shows a hungry father requesting from his two children instructions on how to properly make a peanut butter and jelly sandwich.

Many failed attempts take place before a successful sandwich is enjoyed.

The point of the video…

Context Matters

Unfortunately, we operators, administrators, and developers take for granted how close we are to a process. When the time comes to document the procedures for a repeatable process or share instruction with customers on how to properly complete a task, the solutions are lacking. We’re lucky if 60% of the process is accounted for.

It’s virtually impossible to document something from the beginning, but creating a log of all the steps during the FIRST attempt is critical for gathering all the fine details where context could be lost or partially neglected.

Thankfully with cloud solutions, SaaS products, and Infrastructure Configurations deployed as code, creating repeatable outcomes has become much more probable. There is still much room for improvement.

So remember then, when documenting the right order for the deployment of the process or firing off an automation script you account for the fact that ‘X’ service needs to be run and allowed to reboot (approximately a 45-second lapse for expected result) before the next step in the process can be executed.

This is a terrible example. You’d get more out of this post if you take about 6 minutes to watch the video and think to yourself how easily you can misrepresent all the requirements needed to complete an operation when writing your next SOP.