Forum OpenACS Q&A: OpenACS Documentation

Posted by Alfred Essa on
I would like to help out with maintaining the OpenACS / .LRN documentation. I plan to start with the installation documentation. I am approaching it from the point of a newbie, so this should be interesting. I also plan concurrently to look at ruby on rails and follow their installation documentation.

May I ask who the "active" maintainers are? I see Joel Aufrecht. Vinod has contributed quite a bit. Is Vinod still active and around?

2: Re: OpenACS Documentation (response to 1)
Posted by Torben Brosten on
Alfred, could you be more specific about how "following ROR installation documentation" will change things?

iirc, ROR uses something like (Features at ) Maybe we can adapt edit-this-page to do an html-version of that: given there is a convergence of OpenACS technologies towards that already, including:

BTW, some related requirements for install docs are here:

and some suggestions (in a related thread) from earlier this year in the file storage.

3: Re: OpenACS Documentation (response to 1)
Posted by Alfred Essa on

Thanks. I should amplify my comment about ROR.

1. A couple of years ago I heard a talk by PHP Founder Rasmus Lerdorf. During the Q&A someone asked him to comment on PHP's meteoric success. Lerdorf kept emphasizing the importance of documentation, particularly in winning new converts. That comment made a deep impression on me.

2. If one studies Microsoft and gets past the ideology, I would argue that they do a brilliant job their technology always to the average programmer instead of to the cognoscenti. They truly believe in the unwashed masses.

OpenACS is phenomenonal technology and I ask myself what we need to get more recognition and adoption. My conclusion is that we have to make it as easy possible for the newbie and the average programmer to get started and stay involved in the community. ROR is taking off like a rocket and very much like PHP they realize that it's important to have excellent documentation, good installers, and an open and inviting culture to the newbie. ROR can serve as a good benchmark for us.

I have never taken the time to learn OpenACS. I plan to do so now using the available documentation. Since my technical skills are below average, I can serve as a useful guinea pig. And what I can learn I can apply it towards improving the documentation.

4: Re: OpenACS Documentation (response to 1)
Posted by Alfred Essa on
Is it possible for me to get edit rights to the documentation? I am already finding errors and obscurities.
5: Re: OpenACS Documentation (response to 1)
Posted by Dave Bauer on

Here is a link to the guide to writing documenation. All the docs are in Docbook XML.

The originals are maintained in the acs-core-docs package for general documentation, and in each package under www/doc/ for package specific documentation. In general you should edit the XML source and new documentation will be generated. This is a little steep learning curve just to fix typos, I admit, so another alternative is to submit a bug report. If you feel ambitious, checkout the documentation from CVS and upload a patch file as well.

6: Re: OpenACS Documentation (response to 1)
Posted by Alfred Essa on
Dave, Thanks. I will take a look at the primer.
7: Re: OpenACS Documentation (response to 1)
Posted by Torben Brosten on
Yes, practical documentation makes for good marketing. So does making better use of community using resources, for example, creating a jobs listings area. Being responsive to community needs in general probably helps.

ROR doesn't say much about how to market ROR:

Posted by Orzenil Silva Junior on
Torben, Alfred

Wiki initiative in sounds to me a good start point to maintaining the OpenACS / .LRN documentation for newbies and developers. We have two projects to improve OpenACS documentation and both are there

- OpenACS - The Book, and
- OpenACS Documentation Project

But i think we need some good presentation for wiki package to make it attractive for newbies to collaborate and get informations ready to use about OpenACS.

I was working on wiki package looking at other wiki-like softwares like hieraki and tikiwiki ( and it is not difficult to produce good presentation for this package. I think wiki package is very short and clean and i more easy to use than edit-this-page. Maybe we could work on an improved wiki package to get advanced features for producing documentation .

Screenshots from wiki packages i was working (original code is from cvs oacs-5-2) are in the file storage. the wiki presentation uses mktree javascript already in OpenACS code. Edit mode uses javascript from hieraki with shortcuts buttons for formatting (i didn't see the licence to use it yet)

9: Re: OpenACS Documentation (response to 1)
Posted by Alfred Essa on

For now I will start using the Wiki as the space to add my own annotations. It's much easier to modify and deal with. Thank you for referring me to it.

10: Re: OpenACS Documentation (response to 1)
Posted by Malte Sussdorff on
The decision to go with docbook was a technical one but prevents most people to write good documentation. I just go by myself, who is able to write docbook. I don't write documentation for OpenACS anymore as it is too much work and the result takes ages to come up on the OpenACS site. Whereas a Wiki or an ETP area allows you to quickly work on the documentation and get it going.

So unless there is a real huge need for a docbook kept documentation I'd suggest to convert all documentation into the wiki and write a script to download the whole Wiki into static html pages, so we can distribute it.

Before I make this a TIP I'd ask for comments though if people have major objections.

12: Re: OpenACS Documentation (response to 1)
Posted by Dirk Gomez on
Malte, I wholeheartedly agree. I don't know docbook, I have no time to learn it, and actually I also have no real interest in learning it.

The initial learning curve for OpenACS is very steep because it uses "unusual" technology. Making it easier to contribute is very, very necessary. We could start with making it easier to contribute to the documentation.

So please go ahead and make this a TIP.

13: Re: OpenACS Documentation (response to 1)
Posted by Dave Bauer on
Please lets coordinate to get these improvements into the OpenACS wiki.

The only issue I have is that the Tcl wiki syntax is quite limited, especially for a book/documentation. Also the code is a little tricky to extend with new tags, although I have been able to make some extensions.

It would be really interesting to see better formatting more like MediaWiki (used at wikipedia).

14: Re: OpenACS Documentation (response to 1)
Posted by Dave Bauer on
Another thought,

Docbook was choosen by ArsDigita which was one company that needed a standard for documentation. Now that we have a community maintaining the documentation a wiki or other simpler approach makes much more sense.

15: Re: OpenACS Documentation (response to 1)
Posted by Dave Bauer on
Hieraki is released under the MIT License
16: Re: OpenACS Documentation (response to 1)
Posted by Alfred Essa on
I assume that Malte will TIP to have us move away from docbook and go with a Wiki. Which Wiki to use then? I would urge that we use something like Hieraki instead of OpenACS. We need to get moving on this on quickly and it would be worthwhile to use something that already exists so we can focus our resources. Thoughts?
17: Re: OpenACS Documentation (response to 1)
Posted by Joel Aufrecht on
This seems to be as good a time and place as any to announce that I no longer have the available time to serve as primary documenter for OpenACS. Although the tradition in volunteer projects is that one must find their own replacement before stepping down from a job, that has usually not been possible in OpenACS. Perhaps Al will be so good as to take up the role for the time being.
18: Re: OpenACS Documentation (response to 1)
Posted by Alfred Essa on
Joel and others, I can take this up.
19: Re: OpenACS Documentation (response to 1)
Posted by Stan Kaufman on
Using ROR to document OpenACS would be the ultimate in not eating one's own dogfood, seems to me. From a PR perspective, wouldn't this be worse for OpenACS than not having documentation at all? If the wiki package needs work, that seems to be what needs doing first, eh?

Dave, you created the wiki package -- are you still maintainer? Wiki isn't currently in Bugtracker or on the Packages page, but it should be both places. -- I just added it so bugs/features can be dealt with.

11: Re: OpenACS Documentation (response to 1)
Posted by Carl Robert Blesius on
Could not agree more Stan. What is the point if we do not use our own dogfood?

Wiki based documentation would be great, but the wiki backend we are using is lame. Compare the formating options we have now: with the one wikipedia uses for example:

For now I think we are better off using other options we have in the toolkit until we have something that is halfway decent. The wiki markup we have now is not sufficient for documentation and would lead to chaos. I think Enhanced Text for example is superior ( ) and it provides a two way street so end users can pick different formatting options on the fly (e.g. html).

I agree that making it easier to edit our documentation is very important for the project. I would not mind sticking with docbook if we could automate the steps required now and provide a web interface for easier editing so we get contributions from the people who actually use the documentation (I bet most of the people who have cvs commit do not refer to the docs on install for example), but no automation has taken place and right now it seems the documentation is stale as a result of being hard to edit.

I have looked at form based text-markup options in the past and the ones I would like to see us use are Markdown and/or Textile (or we just use the mediawiki code, but from what I have heard maintenance and changes to the spaghetti behind it are difficult -- their are advantages and disadvantages to the early anarchy that successful project is based on).

Nice part about Markdown and Textile is they both produce clean valid (x)html

Philosophy matches what we want in documentation

There is also a converter available that goes from html to markdown format (apparently an further evolved port of Lars Pind's original to Python by Aaron Schwartz)

------------- (some source is here) (markup examples)

Could we enhance our enhanced text with Markdown or Textile formating?

What is the simplest solution with the most bang? How can we get something running quickly based on what Daveb has started with the wiki?

I do not think docbook markup is the problem (the kind of person that would read our documentation in the first place could figure it out in about 20 minutes and make changes immediately). The problem is the overhead that comes with cvs versioning for this part of the project.

Maybe there is a web based docbook editing interface we can plug in on Maybe we can just use the same Markdown/Textile/etc. code (as cgi's?) and create a plugin infrastructure as other projects have?

Not sure, but if their is an easy way to get Makrdown running inside of DaveB's code we would have a pretty killer wiki right away.


P.S. Other formats I found after some searching:
Part of the docutils project (this a project worth looking at, combination of structure and simplicity... even has a DTD) (another python based project)
BBCode (could not find a direct link to the source, but here is an example of it in phpBB: )

P.P.S. Interesting message from a similar discussion Drupal went through:
(they are looking at the problem because they have a "tag soup" from lack of structure and want to be able to transform documentation to other formats easily).

20: Re: OpenACS Documentation (response to 1)
Posted by Nima Mazloumi on
This could be a proposal that could be funded by Mannheim. Maybe someone or several persons can come up with a proposal that contains the most important features required to get a decent wiki for OpenACS and .LRN. I was asked several times by professors whether .LRN has something like a wiki.
Posted by Steve Manning on

Thanks for your hard work on the documentation. Its appreciated.

- Steve

22: Re: OpenACS Documentation (response to 1)
Posted by Dave Bauer on
I converted some of a Python implementation for Markdown to Tcl. My goal was to always offer more/better formatting options, but the Wikit code was already existing so it was the easiest to get working for an example.

I also looked at the Mediawiki code and several others but could not see any straigtforward way to take advantage of it.

Of course, the OpenACS wiki code already supports all the options of the new and more.

What formatting do we think is "required" for good documentation?

23: Re: OpenACS Documentation (response to 1)
Posted by Malte Sussdorff on
Can someone tell me why we are not using ETP for the documentation but rely on the Wiki? Once we upgrade to 5.2 the HTML Editor works fine and we have a nice interface for tracking changes I know, I suggested the Wiki in the first place, but I'm not convinced anymore this is the best course of action.

One thing that a couple of people mentioned though: If we change from docbook to whatever, we need to be able to export to HTML as well as Docbook and setup an automated CVS commit for this.

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.

Posted by Tracy Adams on
The think I really like about using a Wiki for documentation is that it is really really easy to link up pages to each other. Just put in the [] and you are done. Plus it keeps track of what pages link to each other - which comes in extremely handle if you do a little planning and structure it right.

I agree with you on the formatting... I'd love the HTML widget or at least the abilty to type in some HTML. Or to be able to enclose soemthing in [] but also determine what the HTML anchor is (wikipedia has this).

I've been told then it would no longer be "wiki-like" :) But I contend the wiki with the HTML widget, combined with [] would be killer.

26: Re: OpenACS Documentation (response to 1)
Posted by Andrew Grumet on
I support moving the docs to a wiki. Let's clear out the obstacles and make it as easy for volunteers as possible.
27: Re: OpenACS Documentation (response to 1)
Posted by Dave Bauer on

I think a wiki pretty much gives you a similar function. You can create each "fragment" as a wiki page, and then link them and organize them how you want.

If we seriously need a better wiki, what would it take? What formatting features are required that we don't have? See

28: Re: OpenACS Documentation (response to 1)
Posted by Ben Koot on
Editme has an interesting list of features. Maybe some are usefull to look at.
Well, just how bad is DocBook? I've never attempted to use it, so I am genuinely curious. Malte and others who have, can you give us a rough idea please: How much time did it take you to come up to speed on DocBook, and once you were there, how pleasant and efficient was using DocBook compared to other markup tools?

As far as markup languages that can emit multiple output formats (HTML, PDF, man pages, etc.) go, has anyone used Scribe? It sounds very powerful.

Also, how do all these Wiki syntaxes compare to simply using straight good-old HTML? Or LaTeX, for that matter? In other words, what is the win with using one of the various specialized (but rather ad-hoc?) Wiki syntaxes?

30: Re: OpenACS Documentation (response to 1)
Posted by mark dalrymple on
I've written a book (now in its second edition) using DocBook. The markup itself isn't any worse than doing straight HTML. Getting a working toolchain was painful. Once that was done, nxml-mode in emacs makes things livable. Using the docbook source to create the structure of a website was a nice bonus. We're using the SGML toolchain because the XML toolchain doesn't produce PDFs of good enough quality.
31: Re: OpenACS Documentation (response to 1)
Posted by Nick Carroll on
I support use of a wiki too. At least if I contribute something I will be able to see the results straight away.

As with the current method, I submitted a docbook file containing some updated problem sets to OpenACS a while back. However I don't think it was included as part of the documentation, or it was and I just can't find it. :) I found that a bit annoying, and have been a bit slack on contributing more documentation as a result.

The only problem I have with a wiki is what if someone wants to print out the documentation? Should the wiki some how collate all pages into one long printer friendly page that can be printed?

The way I see it, docbook gives us more freedom on how to present the documentation. However it makes contributing documentation a little more painful by having to setup docbook and learn a new markup. A wiki provides fewer barriers of entry for contributors, but it means all documentation is stored within the database making it trickier to print the docs as a book.

32: Re: OpenACS Documentation (response to 1)
Posted by Nick Carroll on
One more thing, DocBook is a great tool if you are writing documentation by yourself, eg writing a book, thesis, etc. However, would it support documentation written by a community?

The process for contributing and publishing documentation would be so much more convenient and transparent to the community using a wiki. We can have a number of maintainers that can act as editors, so that they can proof-read the documentation that was contributed before publishing it. With docbook, we rely on fewer maintainers, as in the current case, one or two. Joel and Vinod have done a great job at it, but I feel that it is a burden that can be shared across the community.

We also have to consider that the current method isn't working, and we use docbook for the current method. Do we need a better process if we choose to stick with docbook? Or do we need a different tool, such as a wiki?

Getting up to speed on docbook took me half a day for being good enough to write OpenACS documentation. Then it took me again half a day to figure out how to use the provided scripts to generate HTML out of the docbook file. So it is not a problem of the Docbook format. It is more a problem of the steps involved which will scare the casual user from editing documentation.
  1. Download the documentation source code
  2. Use a decent editor for docbook (I used emacs) to edit the documentation. Make sure you keep up the markup
  3. Generate the HTML out of it
  4. CVS commit both files to the repository
  5. Make sure you are on the correct branch. Commit again 😊
  6. Write an email to Joel to update the documentation on
  7. Realize Joel is busy, login to and do the update yourself (This steps used to work for OCT members, now this is restricted to even less people).
Compared with
  1. Login to
  2. Edit the documentation
  3. Reflect in glory about your excellent work
it seriously lacks user friendliness.
34: Re: OpenACS Documentation (response to 1)
Posted by xx xx on
I think a wiki pretty much gives you a similar function. (compared to CMS).

Daveb, IMO, a wiki with its markup is for coders more than for the general public. For openACS documentation that wouldn't matter, but do you really prefer a working wiki to a working cms in the toolkit? XCMS_UI allows you to edit content as well as the source of the template.

You wrote xcms-ui as yet "another content management UI". It is located under packages (not contrib) in cvs. I thought it was promising, but not much has happend in the last 17 months. Why did you shift to creating the wiki package instead of expanding xcms-ui?

The xcms-ui preview at is broken. I remember installing xcms-ui was possible but there were quite a few bugs. At the time, you thought parts of your local code hadn't made it into cvs. I've seen claudio, michele, randy, guan try but don't know their outcomes or experience. If anybody succeeded to create a working xcms-ui instance, could you comment on using it for the current purpose?

Or might Greenpeace cms be useful as referred to here?

35: Re: OpenACS Documentation (response to 1)
Posted by Dave Bauer on
Wiki markup can be made easier with javascript widgets similar to wikipedia. That's not a big deal.

The ease of editing, managing, and linking pages is why I prefer a wiki for documentation. The learning curve is very shallow for a wiki. The interface for a usual CMS is much more complicated.

XCMS was built for a client, and after that job, I contributed the code, hoping someone could continue work on it if they needed it. I unfortunately haven't had time for it. I think the user interface is barely usable for a CMS,a nd for managing documentation, its just wrong.

I like the ability to link to any page more than a hierarchy of documentation. If you want to replicate a book in computer form a hierarchy can work well, but I think HTML and the web offer a better way of using documentation.

36: Re: OpenACS Documentation (response to 1)
Posted by Dave Bauer on
I posted a review of the OpenACS wiki compared to Mediawiki
37: Re: OpenACS Documentation (response to 1)
Posted by Carl Robert Blesius on
A related post to the AOLServer mailing list is attached below (Dossy dealt with one of the data migration issues by not dealing with it).

Also worth noting: We had issues with a wiki migration at work recently. We moved from Mediawiki to XWiki and the person in charge of the migration ended up migrating content by hand (trying to convert from one wiki format to another was regex purgatory).


Date: Thu, 6 Oct 2005 21:57:20 -0400
From: Dossy Shiobara
Subject: AOLserver Wiki is now running MediaWiki!


I know folks haven't been thrilled with the overly simple WiKit software
that was being used for the AOLserver Wiki, so I went ahead and set up
MediaWiki 1.5.0 and migrated all the content over to it.

The upside is that, yes, the AOLserver Wiki is now running on MediaWiki,
with all the niceness that brings (robust formatting capability, etc.).
The downside is that the entire URL structure has changed (for the
better, I guess) -- but that means all the old links into the Wiki are
now "broken."

While it is possible to create wiki pages that would have redirected
from the old URLs to the new, I just didn't have it in me to go and do
that. I'm sorry.

I'd like to hear what people think now that the wiki is running
MediaWiki. Will this encourage you to use it more? Less?

-- Dossy

38: Re: OpenACS Documentation (response to 1)
Posted by Nick Carroll on
So what did we end up deciding on?
39: Re: OpenACS Documentation (response to 1)
Posted by Alfred Essa on
Let me try to summarize this thread from my own jaundiced and extremely biased view.

1. OpenACS documentation sucks and needs to get better fast. This is not a reflection in the least bit on the community. Those who have maintained it (e.g. Joel, Vinod) have done a superb job. Developers want to program and innovate and that's been the focus of most of the developers. And I don't blame them.

2. We need more contributors to documentation. This should be a no brainer. If we want people to contribute, we need to make the entry barrier approach 0. This is why Wikis are great and they have proven their worth. Docbook reminds me of the system that I used to write my thesis on the mainframe. Yes, I am that old. So fugged about it. Let's go with Wikis.

3. If you follow me thus far, then the question is which Wiki to use. Here I am ambivalent. My immediate gratification instinct says go with a tool other than OpenACS. But long term view says that if OpenACS is a "community system" then there are two tools it must have: wikis and blogs. Neither one has to be great, but it should be good enough. I lean, therefore, to using the OpenACS wiki with the proviso that it will get some attention from all the stud programmers (men and women).

Anyway, it would good to make a decision on this soon.

40: Re: OpenACS Documentation (response to 1)
Posted by Caroline Meeks on
Solution Grove is using Wiki extensively internally. We use it for our public pages and for client use cases and meeting notes. I think its good enough. Its also not hard to improve if you find some must have feature we don't have yet.

I vote for using our wiki.

41: Re: OpenACS Documentation (response to 1)
Posted by Nick Carroll on
I second the openacs wiki too. I've seen how Solution Grove use it, and it is very impressive. Just need to learn the wiki language though.
42: Re: OpenACS Documentation (response to 1)
Posted by Torben Brosten on
Well, ROR project is running into similar problems with managing documentation:

It seems to me that the solution is not an exclusive choice, but to manage the available resources well.

Topics that change fast, fragment by system etc (such as install docs) should move to the wiki, and docbook be used for more structured documents, where presentation formats can be changed on the fly...

43: Re: OpenACS Documentation (response to 1)
Posted by Simon at TCB on
Don't know much about the current Wiki. Does it use the content repository? If it did then at least the underlying content would be available for 'other' uses in a more application-neutral form.
44: Re: OpenACS Documentation (response to 1)
Posted by Torben Brosten on
I agree that current docbook implementation does need work. Maybe we can simplify the structure to more closely resemble a book, and limit using tags to those that work in 4.x and the work-in-progress, simplified docbook5[1]?


45: Re: OpenACS Documentation (response to 1)
Posted by marc spitzer on
if you need a formating language how about POD for the wiki language?  It was powerful enough to write the camel book and is simple to learn.  you get done translaters for multipile output formats also.