Forum OpenACS Development: Re: document builder from xowiki pages

Collapse
Posted by Torben Brosten on

Thanks for pointing out xowiki .42. I read it, but did not comprehend it's significance here.

"in any way, you need a way to define a page order and maybe additional filtering criteria."

Yes, creating a separate "table of contents" (TOC) page seems consistent with that.

"spidering n levels deep" does not make much sense. there are no "primary categories".

For formal documentation, you are right (perhaps by definition?).

"I am not very happy about the categories of the openacs.org/xowiki, since orthogonal concepts are pushed into a single category tree, where one needs a polydimensional categorization. for example, for each package, there could be code statistics and requirements, documentation of the package, future plans, etc. For example, "kind of documentation" and "package" are orthogonal concepts. There should be certainly some requirements engineering for the categorizations... The pure liberal wiki-approach is great for building a knowlege base, producing good documentation requires more governance.

Yes. Good point. I have left categories to those who prefer to use that method to access content. As I see it, readers should be able to find content within 5 or 6 clicks from a well organized TOC --no categories required. Maybe we can get categories to comply with general documentation requirements --even if it means giving categories a separate requirements page to start with ;)

Collapse
Posted by Malte Sussdorff on
How about starting by adding sections to the xowiki pages just as we have from the full import of the official documentation at https://openacs.org/test-doc/ ?