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

<blockquote> >* Talli Somekh <mailto:talli@museatech.net> [27Jun03 10:07]:
>>hey,
>>
>>have you seen this stuff?
>>
>>http://svn.collab.net/repos/svn/trunk/doc/book/tools/readme-
>>dblite.html
</blockquote>

<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
>similar.
</blockquote>

<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?

http://www.docbook.org/wiki/moin.cgi/DocBookAuthoringTools
</blockquote>

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.

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?

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?

talli

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
is:

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

1a) when we ship 5.0, update openacs.org 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
      marked

  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
      "dotlrn"



  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.

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

You can try my work under: http://convee.de/docbook2pdf.php

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?