Teresa's DocBook vs. DITA article

posted 08:34PM May 03, 2008 with tags day dita docbook by Lars Trieloff

Scott Hudson points to DocBook versus DITA: Will the Real Standard Please Stand Up? (slides here at dev.day.com) wriiten by my colleague Teresa Mulvihill. Scott points out that DocBook can be used for single-sourcing out of the box, thanks to support for XInclude and I would like to add that we at Day are currently in the process of translating our documentation to DocBook (not DITA) and first results are looking very promising. We are using Wilfried Springer's DocBook Maven Plugin as the driver of the processing toolchain, which is powerful, because we can integrate documentation development tightly with software development, sharing the same repository, using the same branches and tags and using the same build process.

| Comments[2]

DocBook XSL Stylesheets 1.73

posted 11:33AM Jul 24, 2007 with tags docbook maven stylesheets xsl by Lars Trieloff

A new version of the DocBook-XSL-Stylesheets has been released: The full release notes are available at Scotty's Engineering Log. This means, the bug when using the Stylesheets with Xerces should be fixed, and the dependencies of the Maven DocBook Mojo can be updated.

Supporting Technical Documentation Processes with Open Source Tools Slides Online

posted 11:03AM Jun 15, 2007 with tags collaboration docbook mindquarry opensource process techdoc by Lars Trieloff

My slides for my talk Supporting Technical Documentation Processes with Open Source Tools held at Linux Tag 2007 in Berlin are available at SlideShare: Supporting Technical Documentation Processes with Open Source Tools Slides.

Late Ironly

posted 10:46AM May 22, 2007 with tags docbook fop mathml by Lars Trieloff

Jeremias Märki blogs about MathML for FOP. This is ironic, because I looked into DocBook first six years ago due to its support for MathML. I wanted to take notes for my studies in an XML-format and quickly found MathML. But embedding MathML in XHTML seemed no good alternative to me, so I looked further and found DocBook. Since then I intensified my efforts with DocBook as you know, but only a small subset of XSL-FO processors (Antennahouse) was capable of processing MathML. And this subset was much too expensive for me. Now. six years after my inital steps with DocBook and MathML, it looks like a viable open source alternative will emerge.

Eclipse Corner uses DocBook

posted 12:06PM Feb 09, 2007 with tags docbook eclipse tips by Lars Trieloff

Wayne Beaton describes how he uses DocBook-XSL customization layers to generate HTML version of the articles at Eclipse Corner. One article already using the DocBook setup is Unleashing the Power of Refactoring and it looks quite good. Wayne resumes:
Thus, while I quite hate fiddling around with XSL documents, the power that keeping the content separate from the presentation provides is appealing.

posted 01:46AM Feb 07, 2007 with tags cool docbook gnome inkscape macosx software techdoc by Lars Trieloff

Developing Documentation with Wikis

posted 11:09PM Feb 03, 2007 with tags docbook mindquarry techdoc wiki by Lars Trieloff

Via Gordon Meyer I found Dan Wood's weblog. Dan is one of the developers of Sandvox - one of the easiest and best-looking ways to publish a web site (I've blogged about Sandvox before) and describes his technique of using a Wiki for creating a user manual.

The important thing to note here, is that the Wiki is not the user manual, it is just the tool for creating it. Most wikis have serious problems with usability when they are used as user manuals (no wonder, they are designed to ease the publishing and editing process) - an issue Dan mentions and one thing Dan does not mention, but that often occurs in Open Source projects: Wikis are a good excuse for forgetting documentation and delivering bad documentation.

What Dan and his team does is authoring the manual in the Wiki, then converting it into a proper Mac OS X online help. From my point of view, Wikis are not the optimal tool for authoring technical documentation, there are many specialized tools for this purpose that yield higher productivity, but this does not mean that Wikis do not have their place in a technical documentation process.

Wikis are ideal for drafting documents, creating content outlines and collecting resources before writing technical documentation. When it comes to actually writing documentation, specialied tools like XML-editors for DocBook come into play. In an ideal world you could at this point continue using the Wiki-principle of collaborative authoring and with Mindquarry's combined versioned file sharing, wiki and task management you've got all tools in one package.

DocBook Online Validator and Converter for $22,400

posted 09:18AM Dec 06, 2006 with tags docbook koders opensource by Lars Trieloff

Some time ago I wrote What is an Open Source Project worth? about line of code count based valuations of open source projects. Koders, a code search engine that measures and valuates this lines of code metric has now spidered the source code for my DocBook Online Tools and values it $22,400.

This is interesting, because coding the DocBook Online Tools took barely more than two days and I wrote it mainly for my Book DocBook-XML where I needed a head start into DocBook editing, validating and publishing.

| Comments[3]