IT Staff and Documentation

I have been working lately on documenting existing systems.  These are not systems that have been recently installed.  Rather, these are production systems that have been so for years.  The worst part of fessing up to this task is that I have seen this situation repeated in every single workplace that I have ever entered.  Everyone always agrees that documentation is really important.  If that is the case why don't we see more of it?

There seem to be two schools of thought on documentation.  The first school seems to think that documentation should happen at the end of a deployment so that posterity can figure things out.  Without mincing words, this school is undeniably wrong.  Let me explain, but first I will describe the second school.

The second school of thought is the one to which I belong.  This school of documentation thought believes that all aspects of a project, IT or otherwise, should be documented along the way.  Why should we take valuable time away from accomplishing the project goals to document?  That question is flawed actually.  The documentation should be a project goal.  How can long-term project goals be achieved if nothing gets documented along the way?  People come and go, sometimes during long project cycles.  Why should each new person start from the beginning?

Documentation is actually really hard to do.  It can be tedious, but even more so it is not always easy to articulate how something works.  Each person who works on a project should have responsibilities to document his/her work.  It should be part of job duties that affect annual performance reviews.  During the design, documentation expectations should be specified.  Documenting a new system or service is a long process that can be simplified by breaking it into smaller pieces.  In other words, do a little bit every day that you work on something.  Waiting until the end of a project and then staring at the blank computer screen almost guarantees that the documentation will not get done.

Here are some questions to ask:

• Who is the audience for the documentation?
• What will the documentation accomplish?
• What are the acceptable tools to use for consistent team documentation?

Make a deal with yourself.  Document a little each day.  Share that information.  What good is a really impressive system if only a small group of implementers can know how it works?  Keeping information secret does not preserve your job.  Smart people will either figure out what you did or throw it away.  If you wrote the documentation, you are still the one who understands the subject best.  Wouldn't you rather be remembered as someone who made things easier for others?  Sooner rather than later, wouldn't you rather take a day off and know that nobody has to interrupt your vacation time or your sick time with or without kids to ask simple questions that you could have answered in the documentation already?