Documentation....A huge hassel.

I once failed a class because I did not create any documentation to go with the program I had coded. The class was Business Programming - C++. The only assignment for the entire class was to build a database backed program. I choose to do a bookstore inventory program. I wrote the program during the final weekend of classes. When my professor went to grade it, it crashed. I didn't think he would try to enter a string when I was asking for a number. Why would he do that? Because end users would do that, that's why. He gave me an F, not because the program crashed. He expected it to crash. He gave me an F because I didn't provide documentation on how to recover from a crash, or any documentation on how to use the program. I thought it was obvious. NOTHING is obvious to a user, lesson learned.

As I progressed through school, documentation was always a key part of whatever programming, web design, or software development class I was taking. Comments in code? Better be there, or points off your assignment. Wireframes for your webpage....half of the assignments for one of my classes.

At one of the jobs I've had, I asked if there was any documentation for the program I was going to be working on. I was laughed at. For another project the user manual was five years old, which is way out of date, and I was told that there was no point in referring to it at all.  I'm sure that this is not the case at every company, but most of my co-workers seemed to think that this was totally normal.

I think that documentation is a very important part of a project. This is why a significant portion of some classes are spent on how to do documentation correctly. I really wish we had a design document for my current project. Not so that I know what I'm supposed to do doing, I already know that, but so that I can point to it and say, "this is why the program was created this way". Documentation takes time to create though, and time is money. I work in what I feel is a volatile environment, one where changes to program requirements seem to happen on a regular basis. This is not a productive environment to code in, at all. This is usually the result of the customer not knowing exactly what it is they want, or the lack of a design document and a process to go through to get something changed on it. But what’s done is done and there isn't really a good way to go back and fix it. Not without moving backwards, which is something you never want to do. It kills morale, and in the case of doing contract work, makes it seem like you've wasted time and money. So the solution is to keep trucking forward.

So why don't we start doing documentation? Spend a little less time on coding in order to get our documentation to where it should be? Because of the volatile environment. Trying to document something in such an environment is a bit of a time waster. I know because I tried. I wrote on documentation on a process. It took me between a week and a week and a half to get it the way I wanted (wasn't the only I was working through, so less than 40 hours). Within a month, it was out of date and needed to be updated. Now, do I spend another week to change it, just to have it go out of date on me again? The process it was documenting was a relatively minor one, and would only eat up a day of my time to explain or show how to set something up. We have a pretty small team and this process wouldn't have to be gone through many times by the same person. So, it was decided that this particular piece of documentation was more trouble than it was worth.

I'm not saying that documentation isn't important. I think it's extremely important in getting a project off the ground. However, once a project has gained some stream, the usefulness is diminished to the point where the time spent to create new documentation hampers the ability to make progress. The classes I took where we were forced to create wireframes for our web applications or programs before we started working on any actual code were dead on. Not just with how important documentation is, but at what stage it should be done. In the beginning of the project, on the upstream, where changes are easy to make because there isn't much to change. It should be part of the overhead cost of doing a project, not an ongoing cost, because the ongoing cost is so much more expensive.

So...documentation is good, as long as it’s done as soon as possible and isn't subject to change very often. Otherwise, it’s really more trouble than it’s worth, as out-of-date and wrong documentation is often worse than no documentation at all since it can lead people astray and waste their time. And time is money.