Documentation is the Most Valuable Thing You Do

You do write documentation right?

Writing or maintaining documentation is probably the most important things that a System Administrator can do, but because you can do it doesn't mean you do.

We are all busy, lots of us System Admins, Consultants, and Developers have multiple tasks and have day jobs so where do you find the time to do this necessary evil?

I learned the hard way, wasting time, continually having to look things up, trying to remember how I fixed that thing I did that time –  enough was enough. I started to write documentation.

So, to be brutally honest – you HAVE to make the time and when you need to know that obscure thing you did that time but can’t remember what you did – you will thank me.

Stop with the excuses

Making excuses not to write documentation is counterproductive.

Developers shouldn’t write documentation. This is probably true, at least for user guides, but developers should write things down especially if someone else needs to work on your code. How would you feel taking over someone else's project and having no idea why something was done in a certain way? Systems guys also need some documentation on how to deploy your code and any specific settings – so please, lovely developers, write stuff down.

If a guide needs to be produced once your project is complete, work with someone who's familiar with, and good at, writing documentation. You will get a lot less grief and support tickets if you have an awesome user guide.

Documentation is difficult to maintain, and must be continually updated. It doesn't have to be difficult. Once the documentation is complete, updating it should be routine, part of the day job, and not take a lot of time. Do not use this as an excuse to not create it in the first place.

I don’t have time. MAKE TIME– imagine how much time you are wasting having to research how you fixed a problem, checking ports or settings on a server, or even finding the servers IP address as you don't have it documented anywhere. Using the "I don’t have time"’ excuse doesn't wash in the long term. The amount of time you use creating and maintaining documentation will be saved in the future, maybe 10, 100 or 1,000 times over.

So how do you write good documentation?

Good documentation is both technically complex and simple to read and understand. No easy task, but it is possible. It doesn't have to be "War and Peace" or the complete works of George R. R. Martin, but it does have to be fit for purpose.

First, what type of documentation are you trying to produce?

• Installation and configuration guides– This is the typical documentation that System Admins produce. Filled with technical information, notes, and links to system documentation or tech notes to resolve issues you come across.
• A User Guide - How to use a product or carry out a procedure. These documents typically involve lots of screenshots and are very descriptive. It can be viewed almost as a step-by-step manual.
• Use cases or case study– This is a less technical document and more of an overview of a product or procedure.
• Developer or deployment notes– These documents are highly technical and to the point. Even a bullet list of steps and settings is acceptable here.

Before you start, see if the documentation (or at least some of it) already exists. You don't need to reinvent the wheel. If you are creating an install and configuration guide, reference the product documentation where you can. Only make notes relevant to your install and any changes made to the standard steps e.g if you customize the screen and move buttons around, document this and include screenshots.

Use a template and adapt it until it works for you

A good template can save you time and effort when it comes to creating your documentation.

Here is an example of a template we use at BCC for Connections system install documentation. You are free to download and use this as we are publishing it under a creative commons license.

If you have examples of documentation that you use for Sametime, Domino, WebSphere etc. please share with the Community so we can all benefit from better documentation.

Documentation is a necessary evil, so Just Do It! You may not like it, you may not want to do it, but you will thank me for it later.

Need help with your Collaboration environment?