Forum OpenACS Q&A: Re: OpenACS Documentation

Collapse
24: Re: OpenACS Documentation (response to 1)
Posted by Simon at TCB on
There seems to be a requirement for multiple document formats, multiple user input, mutliple target audiences and a simple way to contribute.

Coupling this with the constraint that using the OACS is desirable, perhaps this suggests a CMS style solution?

I.e. each author can submit/maintain fragements (these might be chapters, sections and so on), and an 'editor' can compile these into documents. We then have separate transformation templates for the desired outputs. i.e. one for xml, one for docbook, one for html, pdf etc etc..

It would also then be possible to define a 'manual' in terms of a list of fragements, thus making it easier to offer subsets of the entire documentation that are tailored for a particular audience. i.e. an admin manual, a new user guide, and performance manual and so on.

All we then need is simple html based interfaces for submitting the content of fragements and versions.

The Doc book experts can then supply a suitable template and so forth. This approach then requires the minimum technical knowledge for potential contributors.

Sounds like a bit more work initially, but how much time saved in the long run? And how much easier for authors to contribute?

A good worked example of the cms approach as a side benefit.