Friday, September 26, 2008

The Bane of Every Coder

I am an advocate of developer documentation. I understand why smaller, less mature ISVs and IT shops would take the quick and dirty shortcut of forgoing developer documentation. No one wants to do it. It costs money keeping that documentation up to date. Programmers should get paid to write code. Blah, blah, blah.

Larger, more mature, shops should know better. They should realize that the total cost of maintaining large systems, over time, is much less when new developers can accelerate their time to productivity by reading some well written, accurate developer documentation. Also, it's nice to throw the developer documentation at the powers that be (i.e. government, acquiring company, BOD) when they want to know what's really going on. I'll bet that Microsoft wished that they had spent some more resources on writing good developer documentation.

You don't like to do it. I don't like to do it. Nobody likes to do it. But writing quality developer documentation is like filing your taxes. Doing it is better than suffering the long term consequences of not doing it.

1 comment:

Charles Tryon said...

The only thing worse than no documentation (read: skipping doing documentation during development) is inaccurate or out of date documentation. Second only to that is documentation that is so voluminous and fractured that it is essentially impossible to gather any useful information out of it. Believe me, I've seen both.

I suspect that Microsoft has lots and lots of interoperability documentation. The problem is that it's most likely not in a form that is useful to mere mortals or non-Microsoft employees. Look at their OOXML "specification". It's more than 6,000 pages long, and so full of technical holes that you can drive a truck through it.

It's easy to write documentation. It's a lot harder to write good documentation.