Editor's Note: This editorial was originally published on Jan 5, 2009. It is being re-run as Steve is away at DevConnections.

I was having lunch with a friend the other day and he talked about how much documentation he has to complete for a project and he was lamenting on how much he hates writing documentation. But he's a fairly meticulous person and couldn't short-change the job and write less than he feels is necessary, which in this case would be a detailed enough description for a semi-technical person such as myself to recreate the system.

My thought was this was overkill and we argued a bit about it. I write  a lot, and I always tried to ensure there was documentation with a project, but not detailed documentation. My thought was that I would want ensure that someone close to my level could understand what I had done, or more likely that I could remind myself what was in place, but that I wasn't writing for a junior developer or administrator to understand things.

When I learned about programming in high school and college, I hated documentation. We had to write what I consider silly documentation in our code that explained what was happening in each module, probably just to show the professor that we understood it. There were even times when we had to write the documentation first, outlining each section of code with documentation and the filling in the code underneath, essentially duplicating our work.

My viewpoint now is that I want to comment enough so that someone of close to my skill level can understand what I've done. I know that most of this documentation will get used in two situations, a disaster, or I've moved on. In the first case, you'll make do and just get things running, likely not digging in too deep to the documentation. In the second case, someone of close to my skill level will be needed to keep things running.

In either case, it's highly likely that something will have changed in between the time I've written the documentation and the time that it's needed. I'd argue that poor documentation can be worse than no documentation, or sparse documentation, and I'd prefer having some rough outlines to guide someone, not teach them.

To me, documentation is just a guide to the system. It still takes a human, with some level of required skill and experience, to make it work.