Forum OpenACS Q&A: Manuals Module for OpenACS V3

Does anyone have any knowledge of this module, who built it, for which version of ACS/OpenACS, or where the full version might be available?

talli

* 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

Your thinking is great, but wouldn't a documentation template do that for us? Plus, there's the issue of exporting the document to different formats (if done in HTML, HTMLDOC does a nice job of generating PDFs).

I agree that writing in DocBook can be daunting, but at least in Debian, getting the tools to work right was not very hard. One apt-get and that was it. Okay, maybe 2 (I installed psgml for Emacs).

The only other thing I had to do was to glance through the LDP-Author-Guide-HOWTO and find their stylesheet, and use it. Following their instructions wasn't hard.

Then psgml does the rest of the job much easier. The cool thing about using DocBook (that I know of) is that it generates the indices, links, and is exportable to different formats through Jade.

Another option that can help is using LyX. It'll generate DocBook. I wrote the initial OpenACS docs using LyX and it served me quite well. I later switched to Emacs+psgml for the added flexibility.

What we have to get here is people that are willing to mess with the system/whatever and write about it.

Vinod, thanks for the link.

Roberto, it sounds like you had a much better experience using installing DocBook than I. I don't even remember what I had to do to get it installed.

Whether the simple Manuals module is used as a starting point, or DocBook, we need a howto linking to the software that has to be used. I don't think we can assume everyone will switch to Debian. However, my thought is that we can get it setup and working so that it can be used over the web by anyone, like the Manuals module.

Does anyone have a good Howto on installing DocBook/Jade? (Maybe my unread copy of O'Reilly's _DocBook.._).

Oh, I'm not saying that DocBook is the solution to all the documentation woes (nor I am an expert on the subject), but it seems that a good chunk of people that know what they are talking about are using it for very large amounts of documentation. And, although it is excellent for software documentation, it certainly can be used very well for other purposes.

To get it installed in Red Hat (and its derivatives) it should be pretty simple too. The hardest part (it was for me) is using the right catalogs/stylesheet.

The nice things about DocBook is that a) it frees the writer from worrying about presentation (letting him/her fous on content), b) there are lots of tools to work with it, c) exportable to several formats.

Oft times I've gone to the PostgreSQL documentation source looking for "how did they do that" and found some great answers.

Some good links are: