Forum OpenACS Q&A: Response to Manuals Module for OpenACS V3

Collapse
Posted by Talli Somekh on
Hey Tom, I outlined some thoughts in Jerry's post here (https://openacs.org/bboard/q-and-a-fetch-msg.tcl?msg_id=00025b&topic_id=11&topic=OpenACS) but the basic idea is to have a standard way of writing documentation so that it can be made available in a number of different ways. For instance:

* It would be nice have an executive summary written that is understandable to both techies and non-techies. This summary should be reasonably full and explain the purpose of the module, how it was written and what packages it uses. This would be a very tough thing to do because it should be understandable for anyone that comes to it. But once this is done everything else is ready.
* There should be instructions on how to install a new package, even if it's a brain dead procedure. There will probably be instances that are non-trivial and will require a little bit of handholding.
* There should be a full and complete technical discussion of the module.
* There should be a list of features.
* It should be reasonably integrated with SDM (long term project).
* There should be a discussion of future future features that will be included.
* As is currently (or at least in 3.X) the norm, the data model should be in a separate file from the exec summary, the full discussion and everything else. In fact, I think that each of these sections should be separated so that you could group all the exec summaries, or all the data models, or all the tech discussions in a single PDF or something for download.

I think that I'm basically proposing that we specify a data model or even a very lightweight module for just writing documentation. We have written a cool tool that will let us do this reasonably easily for openacs.org.

This may seem like overkill, but I think that documentation is critically important so having a standard way of organizing it would be very helpful. This could be specific to the openacs.org site, or it could be a module that anyone could use for their own purposes.

Does this make sense?

talli