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

Collapse
Posted by Malte Sussdorff on
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.

Collapse
Posted by Emmanuelle Raffenne on
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.