You Get What You Pay For

Sunday, April 25, 2004

Although the market price for a given good or service isn't always considered to be as accurate as it should be in a perfect market, real markets are mostly correct in that they pay very little for something that doesn't take a lot of effort to produce or provide. But there's an underlying principle which applies even if there is no buyer nor seller, but rather some in-house work that's to be balanced against some internal benefit striven for. In the same way that, in the market, the price is a good indicator of the value of something (although some would disagree here), the time and effort it takes to develop something for one's own use is a sure indication of its worth. The problem with non-marketable activities is that predicting the cost/benefit equation is harder, especially if you're acting as a salaried employee at the workplace. Software development is no exception.

If it's easy to generate so-called (API) documentation for a piece of software by running some tool over the source code, and if that tool is freely available over the internet, does this alone mean that generated documenation hasn't much value?

Because it certainly looks like that to me. What's valuable (and hard to do) about documentation is providing the actual content, the intellectual effort to write plain English with full stops and all, to inform about facts that aren't already known, to take a bird's eye view instead of a narrow-minded method-level narration. It isn't easy to keep the docs up to date, either. But you already know good documentation has to be like. Whether or not the doc tool can spill out RTF, Postscript, HTML, or even XML (so that kids can play with XSLT) isn't really interesting; but don't forget the magic words: "at the click of a button". API docs are for developers, and I don't see the difference between reading a web page and a header file in this case.

Back to the market price analogy: if the market doesn't pay much for something that is easy to do, it's because prospective buyers can do it easily themselves, too. Here's the similarity to the coder who reads generated API docs. All of this doesn't mean that there aren't activities that have a better cost/benefit ratio than others. I can't put my finger on it, but the saying that "you get what you pay for" has a much broader applicability than one would think.

At this site, you get what you download. There are a couple of new items on the downloads page: the Media CGI application, and the .NET Sheet commandline spreadsheet.