Forum OpenACS Improvement Proposals (TIPs): TIP #111: Documentation in Wiki with book mode

As there has been a lengthy discussion https://openacs.org/xowiki/Documentation_Project_Discussion and I have the option to improve on the documentation in July August as part of a training effort I do on the side, I propose the following:

1. The official documentation for OpenACS will be available in XoWIKI running in Book Mode.
2. Alternative roads to read the book will be provided in line with pages in a special section at the beginning of the book describing the table of contents like https://openacs.org/xowiki/docs-admin-toc
3. Additional pieces of advise remain at /xowiki. This will be the place to quickly post up ideas, discuss things and share ideas. Once that can be transformed into a proper structure it should be added to the BOOK.
4. https://openacs.org/test-doc/ will be used as a basis to work upon. This is an import from the current docbook documentation
5. A new section V will be added for package documentation. This will take the best from the menu structure at https://openacs.org/xowiki/acs-content-repository (not the page, the category structure is important) and https://openacs.org/xowiki/ACS_Content_Repository. The latter packages section will be removed from the /xowiki pages. Links to the former section (which contains the CVS commit) will be given from any documentation page in section V.
6. A link at /doc is provided stating that the delivered documentation is outdated and people should go to https://openacs.org/test-doc (or whatever that URL will be) to check for the updated version.

Once this TIP is implemented (read: after the summer) we can start discussing how to include the XoWIKI in the tarball, but this is not the point of this TIP and should be discussed separately.

Approval of this TIP (even with amendments) will stop the discussion on how to document and allow us to start documenting in a proper, single place with clear guidelines as described in the TIP.

Emma, usually I would agree, but the last change to the offical documentation at /doc has been done over a year ago, and that was not a change in content but in the generation. So I don't see much value in /doc anymore. Just do this simple test:

"When was the last time you looked at /doc in your local installation and was it helpful to look there."

and

"When did you last look at /doc and had no access to https://openacs.org/doc";

If the OCT feels we need to first figure out how to ship an up to date version of the documentation, that is fine by me, we could still drop #1, but be aware of the fact that we ship official documentation which is at least 12 months old, most parts even more (installation instructions as an example). What is the logic in shipping such a documentation anyway for a toolkit like OpenACS?

The simplest solution for shipping a documentation in XoWIKI is to drop acs-core-doc package from core and make xowiki part of core with the export from /test-doc preloaded under /doc (where we automatically mount an xowiki instance there). As are a ton of other options, but we had this discussions and no result result so far, therefore apparently there is no pressing need to figure that one out.

Summing it up, I am open to approve the TIP without #1 if you still feel the official documentation should be the one contained in acs-core-docs.

Malte,

"When was the last time you looked at /doc in your local installation and was it helpful to look there."

You'll be surprised: this morning :), to point a colleague to the i18n doc and it helped him. I often go myself to read a package documentation hoping it will be helpful but in this case, you're right, it is rarely.

Anyway. My concern is more about having different official documentation, for 1 version, in the tarball and on the site.

I regenerate them for the tarball. Finals only, not alpha or beta.

I've not taken on the task of updating the online docs, that's a rather large hole in the process, I guess.