Forum OpenACS Q&A: OpenACS Documentation

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?

Torben,

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.

Al,

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.

Yes, practical documentation makes for good marketing. So does making better use of community using openacs.org 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:

http://wiki.rubyonrails.com/rails/pages/HowToMarketRubyAndRubyOnRails

Orzenil,

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.

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.

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.

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?

Joel and others, I can take this up.

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:
http://mini.net/tcl/14 with the one wikipedia uses for example:
http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page

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

Markdown
------------
http://daringfireball.net/projects/markdown/
Philosophy matches what we want in documentation
http://daringfireball.net/projects/markdown/syntax#philosophy

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/

Textile
-------------
http://textism.com/tools/textile/
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.

Carl

P.S. Other formats I found after some searching:
reStructuredText http://docutils.sourceforge.net/rst.html
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:
http://lists.drupal.org/archives/drupal-docs/2005-03/msg00190.html
(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).

Joel

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

- Steve

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 et.al. 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.

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.

Simon,

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

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?

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.

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 openacs.org
7. 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).

Compared with

1. Login to openacs.org/wiki/documentation
2. Edit the documentation
3. Reflect in glory about your excellent work

it seriously lacks user friendliness.

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.

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!

Everyone,

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

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.

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.

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.

if you need a formating language how about POD http://search.cpan.org/~nwclark/perl-5.8.7/pod/perlpod.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.