1-1 start/2007-06-16/1

Well, I must say you tackled the issues surrounding documentation pretty well. You division of areas of concern is right on the spot, and (short of missing one important one) is pretty much the standard division.

However, concerning the usefulness of documentation, I myself have mixed feelings. Overall, I must say that the effort putting into documentation should vary between projects. Large projects that require large teams should, I believe, invest more in documentation than smaller projects. Architectural documentation in small systems is sometimes so obvious that it need no written documentation.

But from my developer point of view, I must say that technical documentation should be replaced by contract documentation. And this type of documentation is precisely the type of documentation that you left out.

I say this because no one needs to reinvent the wheel, and most of the time we use Components-of-the-Shelf in our projects. And nothing upsets me more than a undocumented, completely not obvious behavior that someone decided to implement. And because we always think that these things do not break, we spend most of our time chasing what we think are bugs in our side of the code.

Contract documentation ensures that the client code (we) can learn about every exit situation that we must explicitly handle (or disregard). This, of course, assuming that the documentation is well written.

The next step would be writing these rules in some form of language, meta-code style, that can take us to the next form of formal validation of code. But I digress.

On a final note, I must say I was quite impressed with that MoinMoin plugin, and that it is quite useful for domain driven architectures. Assuming the DML part is dynamically generated, though, I would perhaps suggest the navigability in the documentation by adding links to the proper pages. What say you?