Jeroen,
The OpenACS 4 documentation needs an overhaul, and so any documentation is tremendously useful to the community, so such initiatives should be incouraged..
Let me suggest another approach to the problem, though. Let's have:
- An installation guide. As you pointed out yourself, this part of the documentation seems useful at large already - easy to read and apply.
- An OpenACS Getting Started Guide. Take a look at the old one for OpenACS 3. We need this same guide developed for OpenACS 4, only a more examplified version.
- A developer's guide for beginners. Basically a guide to the person who wants to to extend OpenACS and build on top of the code that's already there. Whereas the Getting Started Guide focused on giving a more general picture of OpenACS (giving guidance on high level subjects such as web services, OpenACS basic principles and ideas, the look and feel, the structure and other general tips on how to keep your installation running smoothly), the Developer Guide introduces the developer to the system on a more specific level showing everything from how to construct basic SQL queries using the db API to making use of the template system. This documentation should be filled with examples (as opposed to the current documentation), simplistic, yet thorough, teaching the developer what she needs to know to succesfully start developing a website using OpenACS. Such matters as the underlying functioning of the kernel should not be touched upon yet, though (see 5).
- An advanced developer guide teaching the developer, who knows how to develop a website using the OpenACS, more thoroughly. The points made in the Beginner Developer Guide are developed further here and topics such as package development, and engineering standards (PL/SQL or PL/pgSQL standards, naming schemes, version numbering etc.), minor subjects such as making european characters work etc.
- Kernel Documentation.
- Documentation packaged with the individual packages including installation notes (should the package installation process differ from that of the standard one), getting started guide (for an example of this see the docs for the lars-blogger package).
A developer in your situation, wanting for example to customize the front page so it shows the latest news, would first have to read the OpenACS Getting Started Guide for a basic understanding and then read the getting started part of the news package (and if the issue is not addressed, write the queries himself).
Bottomline is that there already is a relatively large quantity of documentation available, only either seems to be poorly structured, not linked from anywhere obvious (i.e. aD docs located on arsdigita.com), outdated, not ported, too simplistic or lacking examples. Writing the example guide you propose would be very useful, but I'd rather see that a more unified attempt towards useful, easy-to-read and updated documentation was made and perhaps your example guide could be incorporated into this as a chapter or part of a chapter.
