Wednesday, August 02, 2006

Creating public documentation

The horrid heat here in New York State (yesterday up to 100F/37.7C) and no air conditioning has made it hard to concentrate on work. Yes, work has gotten done, but a bit slower than normal. As part of my work-aversion, I have been catching up on some reading. The text below is from John Blyberg on "Public documentation" in his post Overcoming the "“Tech Deficit" (and helping others to):
Be sure to document both successes and failures diligently. This makes sense not only for future reference in-house, but when made publicly available, those notes can be a valuable resource to others. As libraries, we should be no stranger to maintaining documentation. Of course it's a matter of training yourself to write documentation on a daily basis -- In IT, we're all busy and we all know that documentation is the first thing to slip off the table. Also, some details are sensitive, so you'll need to know which notes to make available and which ones to place under access control.

The point is that if we maintain a good working record of how we've done what we've done, whether it be in a blog, wiki, or even word files, we can point to it later when someone comes to us and asks, "how did you do that?" From experience, I can say that no matter how much time you spend on a project, if you walk away from it for a few months, it becomes very hard to recall specific details. Write it down clearly and concisely.
It can be very difficult to create documentation since often we're tired of the project by the time the documentation is to be written. And sometimes we create documentation that is good for us (the creators) and lousy for others, like the people who will maintain the project long after we're gone.

If you have documentation that should be written, schedule time to do it. Yes, make real appointments with yourself so it gets done. You may not be happy while you're writing it, but I guarantee that you'll be happy later on when you need it.

No comments: