Forum OpenACS Q&A: OpenACS 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?
iirc, ROR uses something like http://www.hieraki.org (Features at http://www2.truman.edu/~ah428/noc.html ) Maybe we can adapt edit-this-page to do an html-version of that: http://bitscafe.com/pub2/etp/development/edit-this-xml-doc given there is a convergence of OpenACS technologies towards that already, including: https://openacs.org/forums/message-view?message_id=304004
BTW, some related requirements for install docs are here:
and some suggestions (in a related thread) from earlier this year in the file storage.
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.
Here is a link to the guide to writing documenation. All the docs are in Docbook XML. https://openacs.org/doc/current/docbook-primer.html
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.
ROR doesn't say much about how to market ROR:
Wiki initiative in https://openacs.org/wiki 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 (http://www.tikiwiki.org) 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 .
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.
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.
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.
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).
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.
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.
Wiki based documentation would be great, but the wiki backend we are using is lame. Compare the formating options we have now:
http://mini.net/tcl/14 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 ( https://openacs.org/api-doc/procs-file-view?path=packages%2facs%2dtcl%2ftcl%2ftext%2dhtml%2dprocs%2etcl ) 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) http://www.aaronsw.com/2002/html2text/
http://www.bradchoate.com/mt-plugins/textile (some source is here)
http://hobix.com/textile/quick.html (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 openacs.org? 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
http://docutils.sourceforge.net/docs/index.html (this a project worth looking at, combination of structure and simplicity... even has a DTD)
http://happydoc.sourceforge.net/ (another python based project)
BBCode (could not find a direct link to the source, but here is an example of it in phpBB: http://www.phpbb.com/phpBB/faq.php?mode=bbcode#0 )
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).
Thanks for your hard work on the documentation. Its appreciated.
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 http://www.writeboard.com/ and more.
What formatting do we think is "required" for good documentation?
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.
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.
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.
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 https://openacs.org/wiki/doc/wiki-help
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?
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.
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?
- Download the documentation source code
- Use a decent editor for docbook (I used emacs) to edit the documentation. Make sure you keep up the markup
- Generate the HTML out of it
- CVS commit both files to the repository
- Make sure you are on the correct branch. Commit again
- Write an email to Joel to update the documentation on openacs.org
- Realize Joel is busy, login to openacs.org and do the update yourself (This steps used to work for OCT members, now this is restricted to even less people).
- Login to openacs.org/wiki/documentation
- Edit the documentation
- Reflect in glory about your excellent work
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 http://tdav.museatech.net:8090/ 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?
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.
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
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?
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.
I vote for using our wiki.
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...