Forum OpenACS Development: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS
On the other hand I still feel, and I think most people agree, that there still is a strong case for technical documentation. At many times it may not be possible to learn easily from the code base what constitutes best programming practice. Different applications may take different approaches, which one should the novice developer choose? Also, as Andrew so well points out, the code doesn't necessarily communicate the design tradeoffs, known limitations or the concepts and use-cases that drove development.
We should try to keep code level information in our docs that can be expected to change to a minimum and rather link to a dynamic api documentation. We must also try to keep whatever duplication still ends up in the docs in sync with the code.
As a reader of technical documentation you are typically aware of the fact that every implementation detail may not be 100% accurate. However, that doesn't render the documentation useless. I believe the design documents that we have inherited from aD illustrate this point.
Our current package developer documentation lacks much of the "why" that Andrew refers to. I've often found myself wandering through package code wondering why it was done that way.
I could see what it was doing, for the most part, but not having a document explaining "the big picture", and the reasons for that design, made the entire effort much more time consuming than it should be.
Instead of reading a blurb of the design of the package, which would help me get to what I wanted to change faster (or find out if I should be even interested in changing it), I had to look through file after file, proc after proc, like a compiler would, to understand it.