Andrew, I really fail to understand why you seem to think that code is _not_ documentation. Since that is the only conclusion I can draw to your objection of my usage. Most of the code I have written I use. Example code which uses code is very good documentation of how, when and where to use an api.
Sometimes I think I fell into a worm hole here. If you look back at my original statements, you will see that a continue talking about documentation that clearly isn't code, so I understand that code is not the only documentation, just one form. If you overlook writing good code, by following a consistent style, it really doesn't matter how much external documentation you write about what the code does. As soon as something goes wrong, no one is going to want to fix it. There are many OpenACS packages which are documented, but are such a mess they are next to impossible to fix.
On the other hand, writing a good document on what you intend to do, what features you think a piece of software should have, what data model you want to use and why, will really save your butt if you have to put a project aside for any length of time to work on something else. I'm finally starting to get to a point where the excitement of a new project gets put into brainstroming, and not into furious writing of code to get something out the door.
