Why I write documentation

What determines if you are praised or cursed once you leave a company?

My co-worker recently left for new fields and on his way out he apologized for any strange issues or configurations we may find on systems he had handled during his time with us.

We all do 11th hour fixes, that temporary patch that we are going to fix properly next week right after the latest time crunch but sadly we all know most of those bandages stay forever. It is hard enough tracking these one off changes or fixes but how many of our systems are being tracked at all?

I have always been in a position of trailblazing new solutions, standing up new servers and products all the time. I pride myself on the quality of the documentation I create throughout these implementations. I was hanging out with co-workers from my previous position and they were telling me about re-building the FOG server I had stood up. I quipped about it being an absolute bear to figure out and they said nope, my documentation made it easy.

Proper documentation is created for your own benefit, and for the benefit of others, it should be robust and living. With how often I stand up new services and servers there are times when I am juggling 2 or 3 new projects. A few weeks down the road when it comes time to revisit the first solution I have already forgotten key aspects or how to handle a specific process. My documentation becomes a lifesaver.

Typically, I am the SME, the implementer, the maintainer, and the one onboarding groups to the product so my scope is rather extensive. In my current role all of my documentation ends up looking like the below outline.

Outline

When I write documentation I am trying to satisfy several issues, not least of which is the Bus factor, I want anyone with a reasonable amount of experience to pick up my document and be able to administer or rebuild my application. I am also trying to create and set standards that can be evaluated and audited.

The best way to write documentation is while you are doing the actions, it may take a bit longer but doing it correctly the first time is always worth it. I find that having to document steps helps evaluate your method and makes you think it out a bit more leading to better results in the future. Anyone who says they don't have time to document, and never has time to document is either too lazy or stretched too thin across duties to be reliable. Both of these are major risks to a company.

I encourage you to be incredibly verbose in your documentation, not just in your install or upgrade processes but also with the administrative tasks related to your service. You want standards to be followed so accesses, permissions and configurations are perfectly clear without having to investigate the settings themselves.

Something that I think is often overlooked is the declaration of naming schemes anytime text input is required: Declare what the format should be and where the values come from. An example would be a Jenkins token seen below for the Ford group to interact in read only with Bitbucket.

The most important part of documentation is that it is living, it needs to be updated and maintained to be effective. As you find issues, better methods, or new processes add them to your documents. A document written once then forgotten is much less useful than one that is maintained.

While all of my documentation may not save me from the curse of the forgotten patches on unknown shared systems I hope that it will save my many dedicated projects from being scrapped or riddled with hap hazard configurations should I win my bus.