DocBook and Booktype

Intro

Moving on from booktype...

php and many software libraries document themselves using docbook, which is an XML-based (i know, ugly) markup language for technical documentation.:

As a semantic language, DocBook enables its users to create document content in a presentation-neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML, XHTML, EPUB, PDF, man pages, Web help[2] and HTML Help, without requiring users to make any changes to the source.

emphasis added. note that it captures logical structure, and doesn't attempt page layout via a crappy HTML editor (like booktype does).

so the HTML it generates can be downloaded in sections, or all at once. it can also convert to windows help fie format (.chm).

for example, here's the php manual documentation download page: http://www.php.net/download-docs.php (note docbook is for any kind of software or hardware technical documentation, and not just for APIs of programming languages.) note the various output formats. also see how users can comment on pages: http://us3.php.net/manual/en/function.sprintf.php (tho that comes out of the CMS they're using, it's supported by doctype)

of course, we wouldn't generate DocBook XML by hand (or any XML). we would need to use a tool. there's many avenues here. one may be to use a plugin for MediaWiki to export pages into DocBook format. all the other formats could fall out of that.

Assessments

• DocBook immediately appears too technical for an average user, and thus, it is of little value for wide scaling of documentation to nontechnical users. In 5 minutes of assessment - i have no idea where to begin with DocBook. This would be a similar turnoff for others who have even less than my minimal programming experience. I favor Booktype as a minimal but sufficient solution. I propose a triple chain going from Control Panel -> Booktype -> Adobe InDesign as a toolchain to assure that documentation gets out there, even if the 3rd step does not happen in this chain. - Marcin