Forum OpenACS Q&A: Response to Commenting on the documentation?

Posted by Roberto Mello on

"Maintaining a full documentation set means that there is a person responsible for making sure it is current(...)"

I'd much rather have a small group of people maintaining the docs, then one person.

"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 either don't understand how the documentation is authored or you worded your phrase poorly. The HTML is simply an output of the SGML sources. Those sources are available in one central location for anyone to pick and change.

"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."

I never told ANYONE "I'll only accept changes to the docs if you send me a DocBook patch". Dozens of folks have sent me things that needed to be changed/improved in the docs through simple e-mail ("There's a typo on section x of doc y"), through SDM submissions in either the form of patches or bug reports much in the way of the e-mail type I just mentioned. Just check the "Acknowledgements" section of each of our docs.

So it's incorrect of you to say that we make users install all the software you mentioned and learn how to use it. If everyone sent me DocBook patches, that'd be awesome, but I'm not picky. Whatever is sent I accept.

I admit that this is not the greatest way of doing things, but it works. For collaboration, we are allowing comments on the /doc section of and I'll monitor those. Deleting things that are not relevant or that have been moved to the doc sources.

A manuals module? Great, if you can solve the problem of outputting to different formats and quality assurance better than what we have now, I'll be very happy to see it implemented (hint, hint!).