Re: Tech doc DTDs

[Bill Lawrence <lawrence -at- mayaviz -dot- com>]

Yves,

Docbook is the mature, well-supported solution used by a wide variety of 
hardware and software vendors.  For example, it's the standard for Linux 
documentation.  Docbook has the advantage of being very well supported 
by both commercial and open-source tools.  For example, you can use the 
open-source Modular Docbook Stylesheets (available at sourceforge.com) 
to convert Docbook into HTML, XHTML, HTMLHelp, JavaHelp, Eclipse Help, 
PDF, RTF, and postscript. 

DITA, from IBM, is the newcomer and is only now getting reasonable 
support from commercial tools vendors.  The open-source tools are more 
than adequate for converting DITA into online help formats, but lag a 
bit in book production capabilities.  DITA is currently used throughout 
IBM.  I think there's an outside chance that DITA may one day supplant 
Docbook simply because of its more modular design.  It was built with 
single-sourcing in mind,  whereas one must be a bit careful in how one 
uses Docbook to make it equal DITA in modularity.

If you're looking to build a large, modular, single-source publishing 
system than can both output various formats as well as publications 
filtered for various audiences, Docbook is probably your best bet.  A 
few years ago I built a Docbook-based system for a large software 
company that, on a nightly basis, converted over 10,000 pages of 
documentation in PDF, HTMLHelp, and Oracle Help. This enabled the 
company to provide updated documentation to reviewers with their nightly 
build.  There are very few other technologies that can achieve that sort 
of thing.

I'm currently building a similar system, though on a much smaller scale, 
for my present employer.

If you are interested in reading a bit more about Docbook, I recommend 
the following article:

http://xml.oreilly.com/news/dontlearn_0701.html

You can also either read an online version of "Docbook, The Definitive 
Guide" at http://www.docbook.org/tdg/en/ or download a .chm version that 
you can read at your leisure.

You can, of course, create your own DTD.  That also requires you to 
create all of the tools to support it, including XSL scripting to 
convert it into useful formats.  If you are up to the programming task 
and you have very well defined templates for both creating documentation 
and for the deliverables, this may be a better course in the long run.  
The great advantage to Docbook is in its very general capabilties.

Bill

Yves Barbion wrote: