Documentation That Works - Part 1

I've read all of the advice articles about documentation. I know all of the reasons to document. I've benefited from good documentation and I've suffered through having poor (or no) documentation. Yet, even after all of this, I find it very difficult to create good documentation. If I create documentation in a Word doc or a help file, I have to remember to open the file up and make the necessary changes every time I do something. Usually I do well at this until an emergency comes up. Then I make the changes to the failing system, but forget in the heat of the moment to make the documentation update. Next thing I know, the documentation is all out of date and I don't know what is good information and what is bad. This gets compounded when I am not the only one forgetting to document.

I have decided that a complete system overhaul is needed. The current system has too many flaws (most of them human in nature). The best solution I have found to replace our current one is a wiki. A wiki is designed to be flexible, have change management, and it is accessable by any of my employees from any computer. This brings the documentation closer to where they are. We chose to start using DekiWiki by Mindtouch. We actually use their free hosting, at least for now, so that we can test out the functionality before we commit to it.

This solves part of the problem. The documentation platform is now closer and a little more accessable to the person making the changes. It also gives us the ability to share out parts of this documentation to a larger audience if we so desire. Finally, the change management allows me to review what has been changed to be sure that the documentation reflects the change made. However, this hasn't solved all of the problem. It hasn't made it any easier to remember to document our changes. It also hasn't made the documentation itself any easier.

This is where my next installments will pick up. Part two will address how a script could be used to monitor changes to key systems and prompt for documentation of those changes. Part three will address the program I am working on developing to automatically create documentation (of my computers using the XML output of my computer inventory script, my Active Directory using some Powershell tools, and other systems). The program won't be complete until it can upload the information right into the Wiki, creating more documentation instantly than we could in a month.