Forum OpenACS Q&A: Response to Code freeze in favor of documentation for 4.7

Posted by Lars Pind on
Great, Jeff! The package developer's guide will be a work in progress, just like the code. If Jeff can get thr process started, I'm certain that I and others will contribute parts of it. But it takes a focused first effort to get it off the ground. Jeff would certainly be a very good candidate for the job. Thanks.

The second part of my point was to try to limit documentation requirements in some places. For instance, there's really no need to include data model or APIs in the documentation. There should be comments in the SQL file, and ad_proc documentation of the Tcl API for sure. But separate documentation should only document the big picture/idea type things, such as defining terms and how they related, e.g. "a portal consists of one or more portal elements, which are instances of portal datasources", etc. Let the data model file tell you the details. Code is documentation, too, as I believe is part of the XP approach to documentation.

So what I'm trying to say is also that we should prioritize our documentation effort, and focus on the most important one, the package developer's guide being an important candidate. If we ask for too much, I'm afraid that we'll get less and lower quality documentation. I think we all agree on that, but obviously the hard part is drawing that line.