Forum OpenACS Development: Re: Best Practices / Conventions / Hidden Features / Howto Document for OpenACS

That is definitely a silly argument, Kjell, so why bring it up?

Good documentation is crucial, everybody knows. But I think nobody can document against the coding force in this community. New code is 'literally flowing in to HEAD' as Ola puts it.

I think the question was where to COLLECT ... If it wasn't for CVS, code itself would be scattered.

Just decide where and how to drop documentation and 'Best Practices / Conventions / Hidden Features / Howto' that one discovers or wants to share.

If not, too bad... we'll search the forum over and over again or we'll ask Tilmann 😊. The community helps out most of the times (thanks!).

Its not actually such a silly argument. These days theres a growing acceptance that the cost/effort curve for technical documentation is often prohibitive. In fact, (and I refer to technical docs only) the code should be the best document available, as, after all, it is the only thing 'guaranteed' to be accurate.

One might argue (as XP does) that if you can't read/understand source code, you have no business working with it at a technical level.

Also, you could argue that documentation actually makes things worse in the long run, particularly when you *know* you don't have the resources. What you end up with is inaccurate docs that confuse instead of help.

In an open, voluntary community such as this then focusing on more 'readable', simpler code may be a better use of labour. Leave doc'ing to a commercial effort.

I should point out I'm not necessarily a proponent of all this, but I'm prepared to beleive that perhaps the whole traditional approach to documentation is flawed.