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.
