Wednesday, September 9, 2009

If You Don't Value It, Don't Ask for It

I recently developed a fairly large web application for a relatively small client. As is often the case on projects like this, no money was budgeted for any kind of documentation. The customer wants to pay for functionality, and documentation has little perceived "bang for the buck."

However, at some point, the customer realized that every time we move the application from one server to another or need to tweak the configuration, they usually need my help. That's no problem right now because I can remote into their server or drive down to their offices if necessary and resolve any problems that come up. However, what happens if I'm not available for some reason?

In the latest release of their site software, the customer asked for system documentation that would help them install and configure the software themselves should they need to do so. I included about a day's worth of writing in the quote and submitted it to them.

The customer approved everything in the quote except the documentation. They asked me to include the docs for free due to the fact that they were spending a good deal of money on the project already.

Now, I'm not averse to giving away stuff on larger projects. I view it as a type of discount. But this project had already received a substantial discount from my standard rate due to its size, and when I thought about it, I realized that documentation is a bit of a sore spot for me.

The problem with technical documentation in general, and system documentation in particular, is that nobody reads it. Because nobody reads it, nobody values it. Because nobody values it, nobody wants to pay for it. On top of all this, writing said documentation is often a painful process that is also demoralizing because you know it won't be appreciated and it will become obsolete (or at least inaccurate) almost immediately.

Another problem is that the people who understand the subject matter best, the developers, are rarely skilled writers themselves. That works out just as well because the companies who hire them would rather pay a lower-salaried technical writer to deal with the documentation. But getting the necessary information out of the heads of uncooperative developers and into the documentation is one of the main things that makes the process painful for the under-appreciated technical writer (yes, I've known several of these long-suffering individuals, including my wife).

The final nail in the coffin is that technical documentation is not usually an income generator. It is an expensive project adjunct with a value that is best calculated by assessing the cost of not having it. Such a vague notion of value is often too subtle for most bean counters to appreciate.

Doing documentation right requires a long-term investment in time and money. You have to be willing to produce and maintain well-written, readable, and easily-accessible documents. But the truth is that few companies are willing to do that for technology that will probably be scrapped within 5 years anyway.

But I digress.

I'm actually one of the few developers I've known who enjoys writing documentation as part of my development work, so I don't mind the idea of putting it together. I'm just not willing to do a bunch of work that won't be appreciated for free.

The way I see it, if something has so little value to you that you aren't willing to pay for it, then just move on and forget about it. If the value finally becomes apparent at a later date and something can still be done about the situation, deal with it then.

No comments:

Post a Comment