Forum OpenACS Q&A: Re: OpenACS Documentation
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).
