Forum OpenACS Q&A: Docbook a barrier to doc efforts?

Posted by Joel Aufrecht on
Talli and I were talking and I thought this should be on a forum.  The issue is, is Docbook a barrier to getting new docs contributions (I think, yes and no; no because I don't mind editing people's plain-text contributions) and what can we do about it?

<blockquote> >* Talli Somekh <> [27Jun03 10:07]:
>>have you seen this stuff?

<blockquote> >looks like it solves a problem we don't have.  It's a subset of normal
>docbook, probably because people were submitting manuscripts using all
>the weird nooks and crannies of DocBook.  That would screw up a
>publisher, but it really don't matter much to us.
>The problem we do have is no wysiwyg tool.  This steepens the learning
>curve and limits erstwhile docbook writers to emacs or something

<blockquote> there are plenty of wysiwyg tools around nowadays. jedit does a nice
job, and the next version of open office will have some integrated
docbook foo as well. i think it already has some nice tools.

there are also some word plugins for docbook.

what kind of wysiwyg stuff are you looking for?

Since I prefer emacs, I'm probably not the best person to select and
recommend and document an alternative.  But one of our documentation
problems is that nobody wants to pick up docbook.  As long as people
write plain text docs, though, I don't think it's a real problem
because I don't mind converting into docbook as part of my editorial
process.  But it could be a bottleneck.

Posted by Jade Rubick on
Advantages of DocBook:

1. automatically generates chapters
2. outputs to PDF and other formats, I believe.

Disadvantages of DocBook:

1. Another learning curve. Developers are already loath to document their work, and it adds another obstacle in the path.

Personally, I think any sort of documentation we host on the website should be editable like an ETP instance, with access limited to a select group. That's the easiest thing I could imagine.

It's only because ETP makes it so easy that I've added so much documentation to OpenACS on my own site:

If it was that easy, I'd volunteer to help with documentation.

The nice thing about this is that it also takes advantage of skills we already have: knowledge of HTML.

And when we get Wiki style input in ETP, producing documentation would be really really easy.

Is there an easy way all the documentation from ETP could be copied to a local instance, or output to HTML, so that local copies of OpenACS would have the documentation as well?

If we are going to choose DocBook as a standard, then we need more documentation on how to use DocBook, and how to document an OpenACS project, with templates, etc.. I tried it a couple times from the tutorial, but gave up, because it seemed like my computer wasn't set up right for DocBook, and I didn't have the time to figure it out.

Posted by Torben Brosten on
My system has not had a new enough set of libraries etc to run a current docbook setup ..until maybe now (I think). I've just installed Debian 3.0r1 stable and haven't checked the "new" docbook yet.

I think docbook is an adequate working format in that it can output to the various web (and other) publishing standards.

Still, I think the docbook publishing format needs tweeking for reader's sake, because one can publish a series of documents more reader friendly than standard output from  docbook.  I'm working on a proposal for changes. Since docbook is an evolving standard, the doc publishing format will hopefully improve as docbook improves (and at little additional effort).  Alternately, we can create a variation on the docbook format at any time without affecting the content (much).

I haven't had a chance to learn/use ETP yet, but like Jade's idea.  Perhaps there is a way to get the best of both worlds: Is there some way to integrate the docbook files to be editable/updateable through ETP?

Posted by John Sequeira on
Several people have mentioned that an advantage of DocBook is exporting to multiple formats...  does anyone actually see that being useful?  i.e.  Is the PDF generated by docbook any better than what you could get starting from easily generated HTML and converting using htmldoc or Acrobat?

i.e. Would anyone actually read the PDF?

I think for documentation,  lowering the barriers to entry should take precedence over output flexibility.  It's fine to say that tools exist to support DocBook,  but wouldn't it be much better to just be able to use the tools for crunching text everyone knows about already?

For those reasons,  I vote wiki or something like it.  This would mean ETP would be closer to supporting it,  and you could still possibly render to DocBook if need be.  For instance,  Almost Free Text (a wiki variant) allows you to write filters that export different formats (html/xml/troff/latexe/etc).  I imagine you could write a DocBook export plugin and satisfy people favoring either approach.

Forget about figuring out:
1) which DocBook tool is most mature and useful
2) what element should I use for this callout or code block
3) how do I get my docs included in the CVS tree
etc. etc.

... Just hit the ETP button and write.

Posted by Talli Somekh on
John does have a point since we are presumably a community of scripting wizards. And if scripting wizards don't know how to convert text to other formats than what do they know?

That being said, there are advantages to using docbook, but even the creator of DocBook (Tom Walsh) has said that he believes DocBook has become bloated and too difficult to get up to speed, let alone master.

Joel has said that he doesn't mind converting the documentation people write up in txt/html into DocBook. Perhaps if those who are spending their time documenting their efforts (and you rockstars know who you are) simply do it in a structured way that is simple but also makes it easy for Joel to convert to DocBook we would have the best of all worlds?


Posted by Jade Rubick on
I think Joel's offer is very generous, but then he becomes the bottleneck in the process. We need to make it as easy as possible to get good documentation up. For me, this means web-based editing, with access controls. It's a eat our own dogfood type of thing too.

This seems like pretty classic collaborative editing issues to me, and also classic CMS issues. As long as there is some sort of structure to it (access controls), something like a Wiki or ETP is something I'd strongly vote for.

Whatever Philip Greenspun's strengths and weaknesses, one of the best points he made about web sites is that the success of a community built web site can be measured quantitatively by the ratio of webmaster contributed content over user contributed content.

This case is a little different, but the principle is the same. The easier we make it to contribute to documentation, the more attention it will get.

Joel has been very good about fixing documentation when errors are found, and he's vastly improved the documentation from where it was at six months ago. Still, wouldn't it be nice if there were two or three Joels around?

Posted by Joel Aufrecht on
First, can we give Jade commit rights to acs-core-docs?

Second, could somebody look at docs/openacs-HEAD and figure out why comments don't show up, even though I added the pages to static-pages?

Third, dribbling this thread forward:

This is of course the big ongoing discussion.  In brief, my preference

1) keep using docbook in cvs.  (With nxml-mode in emacs, DocBook is now, barely, usable)

1a) when we ship 5.0, update static pages so that comments work again

2) when we have a comprehensively better solution, switch

A better solution would satisfy:
  a) Documents which are 'blessed' by the core team are clearly

  b) anybody can contribute a comment any time they are looking at
      documentation, whether it's a local copy or whatever, and all of
      those contributions are available to everybody else

  c) both comments and documentation are associated with particular
      versions (database version, oracle vs postgres, on windows vs on
      mac), and browsing the documentation can be controlled by version.
      (eg, show me core documentation for install, in the right sequence,
      for OpenACS on red hat 9, in german if possible)

  d) We can construct arbitrary paths through the documentation, such
      as "Quick Install" and "Complete production install" and

  e) create a printable document

Our current system, when fixed, satisfies a, partially satisfies b,
could satisfy e, and could satisfy d.

I see the new system as a combination of a new CMS on OpenACS,
categorization, and an as-yet-undefined mechanism to get local data
routed through openacs.

Posted by Luigi Martini on
I feel I am fully entitled to comment on the subject: few people are more ignorant than I am about OpenACS and DocBook.
I need documentation, instruction, examples, comments.
I need text, a lot of plain text, down to generous comments inside the code.
Text and some link would do (plus, full functionality from the "Reader's Comments" at the bottom of the page).
All the rest is a loss of time and effort, at the moment.
I do not mean I do not appreciate Jeff's work (, or Joel's, or all your thoughs about DocBook and the rest: just, we absolutely *need* text first, a lot of plain text and examples.
Much more than I could find till now.
Posted by Andrew Piskorski on
DocBook is certainly an obstacle to generation of OpenACS related docs, articles, etc. (Yes, we have skilled volunteers willing to manually merge non-DocBook content into the DocBook sources, which is excellent, but that's still not and can't be the same as being able to yank the sources from CVS and fix things yourself.)

How big an obstacle I can't really say, as I've never tried using it. Maybe big, maybe small. But I think I've only ever met one programmer who, by choice, preferred to write in DocBook XML.

Part of that is probably path dependent. (E.g., I also know programmers who use and like LaTex but never HTML; but is that because LaTex is better/easier or just because they already know it and don't care to bother with HTML?)

But still, that sounds like a somewhat telling piecee of circumstantial evidence against DocBook to me.

I'd say that for doc formats and tools, priority should be, in order with top priorities first:

  1. Lower barriers to entry, encourage as much contributed content as possible.
  2. Higher quality of docs (e.g., auto-generated Table of Contents), better and easier maintenance of docs.
  3. Better and easier conversion to multiple output formats. (AFAIK to date this has never been a real priority for any real user of OpenACS, and isn't likely to become one either.)
Posted by Andrei Popov on
For WYSISWG -- check out XML Mind XML Editor at  Works for me in most cases (except for nested docs).

In case of Emacs, I've moved away from psgml onto nxml mode -- it feels lighter, albeit not all the nice hooks are in yet.  It is based around RelaxNG, instead of DTDs.

Posted by Thomas Wendlandt on
I came to DocBook rather unwillingly. I decided to do the documentation part of a software project, and was just told "Please use DocBook!" It was hard for me to get into it, but I think it's worth it, as XML processing allows for varios target formats.
I would not yet call myself a professional in DocBook, but I'm trying to overcome the burden of transforming DocBook to PDF (I was a bit dissatisfied with FOP). I'm developing a set of xml handler classes in php, relying on only 2 php libraries: one for xml, one for pdf. No xslt, no in-between step to xml-fo.

You can try my work under:

Until now this can handle only a few basic elements, and it cannot handle any style sheets, everything hard-coded. As long as I concentrate on conversion to PDF, should I work on a css kind of style configuration?

I know there is still quite a lot to do. Please tell me, if you think this online transformation is faster than any Java/SAX/FOP transformation queue.

Is it worth working on this at all, or are there other such online services?