Writing a book with DocBook and a Confluence wiki

We’re in the final stages before sending my book off to the printers. Exciting! While we wait, let me tell you a bit about how the publishing team and I have produced the book. We’re using a Confluence wiki and DocBook XML.

Cover of "Confluence, Tech Comm, Chocolate"Here’s our process in brief:

  • Plan, write and review the book on a Confluence site.
  • Use the Scroll Wiki DocBook Exporter to convert the content to DocBook XML.
  • Use DocBook XSL-FO style sheets to create a PDF file for sending to the printers.
  • Use XSL to generate ebook formats too.

This post is about writing and reviewing the book on the wiki, and converting the Confluence content to DocBook XML – the first two points in the list above. Richard Hamilton, at XML Press, is the expert on the further DocBook processing.

A bit about the book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. Details are at XML Press. It is all about developing technical documentation on a wiki, with a focus on Confluence wiki. And just to be ultra meta, I’ve written the book on a Confluence site. Dogfooding FTW!

Writing, planning and technical review on the wiki

Richard Hamilton and I have spent the last nine months on a Confluence wiki site. We kicked off our planning there in May 2011. Since then, I’ve spent around 400 hours writing the content on the wiki. Ryan Maddox, our illustrator, has uploaded his images onto the wiki. For two weeks in early December, the technical reviewers joined us there too – six knowledgeable and enthusiastic people:

The wiki was abuzz with review comments, opinions and counter-opinions, laughter and chat.

Now it’s gone a bit quiet while Richard and I work on the last stages of book production. When we launch the book, we’ll open up the wiki site too. You’ll be able to join us there and make it buzz again.🙂

DocBook for the publication processes

DocBook is an XML standard for documents, developed by O’Reilly as a means of making their publishing process more efficient. It is now an open standard maintained by OASIS.  Richard Hamilton, at XML Press, uses DocBook XML to publish a range of books on the subject of technical communication. Using a customised set of the open source XSL style sheets for DocBook,  Richard can create HTML, PDF (through XSL-FO), EPUB and other epublishing formats from the DocBook source.

Converting content from Confluence wiki to DocBook XML

So, I’ve finished writing the book and the reviewers have worked their magic too. It’s all on a Confluence wiki. The content is stored in the Confluence database in wiki format. How do we get it to DocBook so that Richard can create the print and ebook formats?

Enter the Scroll Wiki DocBook Exporter.

Scroll Wiki DocBook Exporter is a plugin for Confluence, developed by K15t Software. (A plugin is a small piece of software that extends the functionality of the wiki. It is similar to an add-on for a web browser.) Once you have installed the Scroll Wiki DocBook Exporter on your Confluence site, you can export a page, a set of pages or an entire space, to DocBook XML.

How to use the Scroll Wiki DocBook Exporter

The first thing is to add the plugin to your Confluence site. You need to be a Confluence system administrator, then you can install the plugin in the usual way:

  1. Log in as a Confluence system administrator.
  2. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
  3. Type “scroll wiki docbook exporter” into the search box and click “Search”.
  4. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
  5. Click “Install Now”.

See the Confluence documentation on installing plugins.

You will need a license key from K15t Software. They provide a free evaluation license that gives you full functionality for 30 days.

Once the plugin is installed, a new option appears in the Confluence “Tools” menu, allowing you to export the content to DocBook format.

  1. Go to the page that you want to export. If you want to export a set of pages, go to the parent page of the set.
  2. Click “Tools” > “Export to DocBook”.
  3. Adjust the options in the dialog that pops up:
DocBook Exporter dialog

Scroll Wiki DocBook Exporter

When you are ready, click “Start Export”. The plugin will create a zipped file containing the DocBook XML and attachments, and will offer the file to you for downloading.

A sample of the output

Here is one of the book’s pages on the wiki:

Book's front page on the wiki

Front page of the book on the wiki

And here is an extract of the DocBook XML:

<?xml version=”1.0″ encoding=”UTF-8″?>
<book xmlns=”http://docbook.org/ns/docbook&#8221; xmlns:xlink=”http://www.w3.org/1999/xlink&#8221; xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance&#8221; xsi:schemaLocation=”http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd&#8221; version=”5.0″ xml:id=”scroll-bookmark-1″>
<info>
<title>Confluence, Tech Comm, Chocolate</title>
</info>
<part xml:id=”scroll-bookmark-2″>
<title>Confluence, Tech Comm, Chocolate</title>
<chapter xml:id=”scroll-bookmark-3″>
<title>A wiki as platform extraordinaire for technical communication</title>
<para>By Sarah Maddox</para>
</chapter>
</part>

[SNIP]

<index />
</book>

Index, footnotes and figure captions

The Scroll Wiki DocBook Exporter supports these too. The plugin adds a number of macros to Confluence, which you can use to mark up the index entries, footnotes and figure captions. I’ll write another post with the details. I’m sure many people are agog to know how this works.😉

Working with K15t Software and XML Press

Richard and I have worked on this project with Tobias Anstett and the rest of the team K15t Software.  They are great people to work with: knowledgeable, enthusiastic and energetic. As far as I know, this is the first time anyone has written a book on Confluence for publication via DocBook XML. We have added new functionality to the plugin, especially for the index and footnotes, adapting and tuning as we go.

Thank you all. It’s exciting to help perfect a plugin that many other authors and technical writers will be able to use.

And I can’t wait to get my hands on a copy of the book!

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 29 January 2012, in book, Confluence, confluence tech comm chocolate, indexing, open standards, technical writing, wiki, xml and tagged , , , , , , , , , . Bookmark the permalink. 15 Comments.

  1. Hi Sarah,

    Nice article; thanks for the plug for XML Press.

    A couple of points of clarification. DocBook wasn’t developed solely by O’Reilly. They were part of the early effort, along with HaL Computer Systems, but that effort soon included other participants including DEC, HP, Sun, Novell, Unisys, Hitachi, Fujitsu, and SCO. They formed an organization called the Davenport Group, which managed the standard until around 1998, when it moved to OASIS, where it still lives (in fact, it has lasted longer than several of the companies that started it:).

    It’s also the case that while DocBook is great for publishing, and O’Reilly has had (and continues to have) a big impact on this application of the standard, a large part of the original intention was actually to improve interchange, especially among the group of organizations using the Unix system. At that time, (mid-’90s), Novell owned the Unix system and licensed the software and documentation to a lot of companies, thus the need for an interchange standard.

    • Hallo Richard
      Thanks very much for all the information!
      Cheers, Sarah

    • I’ve written three books for O’Reilly now using DocBook, and the last two were much easier because they now provide all the DocBook to PDF tools remotely. I just commit my DocBook files to Subversion and then a few minutes later they commit the generated PDF into a subdirectory. It worked very well for me.

      • Matt,

        I used that process, too, while working on the DocBook Definitive Guide with Norm Walsh. It worked really well, and I’d like to adopt it at XML Press, though it’s a few items down the to-do list:-).

  2. Hi Sarah,
    just a short question about the sample page you have shown. I see the you have made a subpage for every chapter:
    I. Introduction
    II. Developing …

    I guess that you have numbered this manually ? So if you had to rearrange a chapter you move this wiki page to its correct position, and after that you have to edit every page name to get the numbering right. Correct? Or is there a fancy plugin that takes care of this?

    Kind regards,

    Tobias

    • Hallo Tobias

      There is a plugin that adds automated heading numbers to Confluence. I haven’t tried it myself. Here is a link to the plugin details:
      https://plugins.atlassian.com/plugin/details/16063

      So yes, in this case I’ve numbered the page names manually, and I would need to manually change them if I wanted to renumber them. For the book production process, it’s not necessary to add the numbers. The DocBook processing does that automatically. But I’ve added the numbers to make the content easier to read on the wiki. In fact, Richard has written some scripts to remove the manual numbering before adding the “real” numbers.🙂

      Nice question!
      Cheers, Sarah

      • Definitely an excellent question. I handled xrefs in two different ways, one for chapters and one for figures. For chapters I used the sequence (Chapter 1, Chapter 2, etc.). For figures, Sarah put “Figure X-Y” in the caption, then used Figure X-Y in the text. I essentially used “Figure X-Y” like an id and just linked them up.

        I think the best way to handle chapters may be to do what I did in a project that uses pbwiki. In that case, the author did a normal wiki link to the other page, and our conversion generated xrefs. That made the process insensitive to shifting/adding chapters. That might be a useful addition to the DocBook exporter, and might even be expandable to generating links more generally.

      • Hi Sarah,
        i am using the Plugin “Numbered Headings” to which you are referring myself in some cases. It works pretty well.
        Your can define a lot of different headings and at which depth the numbering should start.

        if you move a chapter to another place everything get renumbered. attentions, not at once. You cut the chapter to move, the old number stays at the old place and the content goes into the clipboard. now you paste the content into the new place. first the old chapter will be seen. but once you click into the editor, it gets renumbered. a little bit weird, but i think the macro as no other chance.

        furthermore you can change a main chapter to a subchapter just by changing the heading type, from, lets say, h1. to h2.. this will change from “2” to “1.1”

        Regards,

        Tobias

    • Hallo Tobias
      Nice! Thanks for all that information.
      Cheers, Sarah

  3. Hey Sarah
    Thanks for sharing this.
    Why didn’t you choose the PDF exporter instead of the DocBook Exporter?
    Is it only because you want to be able to publish both in PDF and ePub?

    Vincent

    • Hallo Vincent

      That’s a good question We chose DocBook because the publisher, Richard at XML Press, already uses DocBook in his production processes. And you’re right, we wanted to be able to produce ebook formats from the same source.

      Once we had chosen the Scroll Wiki DocBook Exporter, we found that it gives us some very useful additional tools. Specifically, I can embed the index entries into the text by adding macros, and we can generate the index when generating the final output. Similarly, I’ve embedded the references into the text, and they can be transformed into footnotes or a references section at the end of the chapter or at the end of the book. (I’ve chosen to put the references at the end of each chapter.)

      Cheers, Sarah

    • Vincent,

      In addition wanting to publish in both formats, using DocBook gives me much more control over the formatting, both in pdf and ePub.

      Richard

  4. I heard about K15t guys from Sherif. I met him last week in Bangalore at the Agile India 2013 conference. I remember using DITA2Confluence Eclipse plugin at Savi Technologies where we ported our XMetaL DITA maps and content to Confluence. It was such a pain to get it right. I guess with Scroll, things have become quite easy. I’ll explore it.

  5. I heard about K15t guys from Sherif. I met him last week in Bangalore at the Agile India 2013 conference. I remember using DITA2Confluence Eclipse plugin at Savi Technologies where we ported our XMetaL DITA maps and content to Confluence. It was such a pain to get it right. I guess with Scroll, things have become quite easy. I’ll explore it.

  1. Pingback: DocBook export and import round trip with Confluence wiki « ffeathers — a technical writer’s blog

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: