STC Summit day 1 – Why not DocBook?

I’m attending STC 2012, the annual conference of the Society for Technical Communication. It’s Monday morning, the first day of general sessions. The weekend has been packed with pre-conference events and socialising too.

The first session of the morning is by Richard Hamilton of XML Press. Richard is the publisher of my book, and I’ve just met him in person for the first time. Up to now, we’ve corresponded by email, wiki and Twitter. It was great to shake his hand.

Why not DocBook?

That’s the title of Richard’s session: “Why not Docbook?” He covered the following points:

  • The schema, and what’s new and what’s happening
  • The tools and documentation
  • The DocBook community

Discussing the schema, Richard emphasised its simplicity. As long as something is familiar and organised, it works. And DocBook is essentially that. The structure is organised around creating a book. You can also generate a number of other formats, such as slides, text, HTML, EPUB, and more.

Richard gave us an informed look into the DocBook schema and its structure. I took just a few notes:

  • Using namespaces, you can embed chunks of other XML into DocBook, such as SVG and MathML. This is really powerful and useful.
  • The latest version of DocBook uses the Relax NG schema language. To customise XML, you often have to do a lot of stuff. But using Relax NG in DocBook, it’s simple – just 2 lines of code.

Next Richard moved onto the tools and documentation available for DocBook, and why they are a plus point for DocBook usage. He discussed Schematron, a language for making assertions about patterns found in XML documents. For example, if you want to say that a footnote cannot contain another footnote, you would use Schematron. Most XML IDEs will apply the rules defined in a Schematron.

Another selling point of DocBook is its stylesheets. Richard recommends a book called “DocBook XSL: The Complete Guide”, by Bob Stayton.

Richard listed a number of tools, including Confluence wiki which has a plugin that allows you to generate DocBook from the wiki content. The plugin is developed by K15t Software.

In the third part of his presentation, Richard talked about the DocBook community. It consists of people using DocBook, and also all the people who can help out. O’Reilly Media do a lot of work in DocBook, and are doing more and more. XML Press is another publisher that uses DocBook as core to its processes. There are a number of open source projects that use DocBook.

On the support side, there are a couple of mailing lists that are very active and very well covered. For example,people will respond to questions about a particular customisation by giving a chunk of code that does the job.

In summing up, Richard says that in terms of generating different output formats, DocBook is number one. And in terms of support, you can’t do better either.

After the presentation, Richard answered a number of indepth questions from the audience. Thanks for an interesting session, Richard, and a great start toMonday at STC 2012.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 22 May 2012, in STC, technical writing and tagged , , , , , . Bookmark the permalink. 6 Comments.

  1. My O’Reilly books are all in DocBook. I really appreciate that O’Reilly handles all the PDF etc generation, since I did all that myself for the first one and it wasn’t trivial. I think the main issue now is whether people use an XML editor or a text editor to write the docbook source. Different tools save the same XML in different ways, making it hard to see what has changed.

    • Hallo Matt

      That’s a good point. When we did my book, we wrote and managed the content on the wiki and then exported it to DocBook for the final publication process. That meant that I could use the wiki notifications to be informed when things changed, and use the wiki version comparison feature (page diff) to see what had changed between versions of each page.

      When we eventually moved the content to raw DocBook for the final publication processes, it was impossible to monitor changes. That made things very difficult.

      Cheers
      Sarah

  2. Having worked with both DocBook and DITA for a couple of years at a previous company, I’d say that both DocBook XSL and Bob Stayton’s “DocBook XSL: The Complete Guide” are the biggest selling points for wanting your source content in DocBook XML.

    Bob’s book, which afaik is also freely accessible online (http://www.sagehill.net/docbookxsl/), is very well written and makes it relatively easy to modify DocBook XSL to generate highly customised outputs (e.g. PDF, CHM, HTML, etc) from a single source of DocBook XML content (http://en.wikipedia.org/wiki/Single_source_publishing).

    “DocBook XSL: The Complete Guide” does assume some basic knowledge of XSLT, which is needed to develop a customised DocBook XSL ‘layer’ that overrides those in the base DocBook XSL library. However, the base DocBook XSL stylesheets have been designed in such a way that it is relatively easy to tweak them — typically, your XSLT code customisations need only be kept to a minimum in order to generate highly customised outputs.

    At that previous company, we started off with our source content in DocBook XML but then a change in management lead us to migrate this content over to DITA XML. I used the DITA Open Toolkit (DITA OT), which ‘out of the box’, allowed me to perform this migration fairly painlessly.

    What the DITA OT provides for DITA XML is more or less equivalent in purpose to what DocBook XSL provides for DocBook XML.

    Unfortunately, I found the DITA Open Toolkit’s XSL stylesheets nowhere near as well developed as DocBook XSL for generating highly customised outputs from a single source. Hence, I effectively ended up with a ‘toolchain’ that converted our DITA XML content (via the DITA OT) to ‘temporary’ DocBook XML files, which in turn were converted (via our existing customised DocBook XSL layer) into highly customised PDF, CHM and JavaHelp outputs.

    As mentioned on Sarah’s other blog post about Using DITA (https://ffeathers.wordpress.com/2012/05/23/stc-summit-day-2-using-dita/) I found the following inherent features of DITA XML made me start to favour DITA XML over DocBook XML as the storage medium for written content:
    1) topic modularity
    2) extremely flexible content re-use through ‘content references’ (i.e. ‘conrefs’)
    When our DITA XML was converted into DocBook XML, the DITA OT would fully resolve DITA XML conrefs into DocBook XML.
    3) conditional processing (which was very useful, but admittedly I didn’t use to a great extent at the time)

    I’m aware that DocBook also has these 3 DITA features and claims that DocBook doesn’t are considered myths. However, I never got the chance to properly investigate these 3 DITA features in DocBook and I’m not sure how readily DocBook can achieve them ‘out of the box’.

    • Hallo Giles

      Thanks do much for this information-filled comment. Very useful indeed. It sounds as if both standards have their pros and cons, but that on the whole you’d choose DITA. It is very useful to hear from someone with such good ezperience of both.

      Cheers, Sarah

      • Hi Sarah,

        Thanks for your reply and you’re welcome! Whilst personally, I’d still prefer DITA XML as the storage medium for documentation, DocBook XML definitely wins when it comes to single source publishing.

        In fact, when I worked with DITA and DocBook back in 2008 now, I recall browsing Bob Stayton’s ‘Publishing DITA with DocBook XSL’ presentation (http://www.sagehill.net/presentations/OASIS2007/DitaInDocbook.pdf), published a year earlier, which gave me the inspiration for developing the DITA to DocBook toolchain I described above.

        I think the fact that the DITA OT fully resolved DITA XML conrefs into DocBook XML gave me the impression that DocBook XML wasn’t really cut out for the 3 DITA features I mentioned above.

        Having said that, it’d be great to know if anyone else who’s dabbled with DocBook XML recently has used it for developing modular documentation, along with content reuse and/or conditional publishing.

        Cheers,
        Giles.

  1. Pingback: STC Summit 2012 wrapup – STC12 « ffeathers

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: