Forum OpenACS Q&A: Golden mean?

Collapse
13: Golden mean? (response to 1)
Posted by Andrei Popov on
<p>If it reads like a rant, it must be a rant, right?</p>
<p>I think it would be impossible to find a "golden mean" here. Maintaining a full documentation set means that there is a person responsible for making sure it is current (i.e. matches the software it talks about), correct (both gramatically and technically) and covers all the important (from user point) items.</p>
<p>You cannot have good documentation unless you have a central point of maintenance (which does not necessarily mean dictatorship). You cannot have central point of maintenance if document content is scaterred between static .html files on a web server, DocBook .sgml files on a harddrive of a maintainer/in CVS and user comments in the database. You cannot have easy collabaration if you are going to have to make users download DocBook sources, install Emacs and PSGML, learn to use diff and patch, etc.</p>
<p>What gives?</p>
<p>I guess one could move through little trade-offs: allow (not in-line) GC in /doc. Add "Get latest copy from CVS" link on a doc page for registered users, or "I want to comment/correct this".  Allow this only for registered users.</p>
<p>Another option is covered in WP -- IIRC you can have it in a "shared" mode, i.e. a presentation can be allowed for editing by others.</p>
<p>How about the manuals module mentioned elsewhere on this site? It may not be great, but it may be a step to a more coloborative documentation creation...</p>