Blog Archives

DocBook export and import round trip with Confluence wiki

This is exciting news for technical communicators. We can export content from Confluence wiki to DocBook and then import it back into Confluence. I’ve just tried it using the Scroll Wiki DocBook Exporter and the RedHat DocBook Import for Confluence.

As you may already know, I’ve written a book. 😉 The book is about Confluence, and the content is on a Confluence site. So I decided to try exporting the book to DocBook XML and then importing it back into a different Confluence space.

In summary:

  • I’m running Confluence wiki, version 3.5.3.  (The DocBook Import plugin does not yet support Confluence 4.)
  • I used version 2.0.2 of the Scroll Wiki DocBook Exporter, a Confluence plugin from K15t Software, to export the content of my book to DocBook XML.
  • Without making any changes to the XML, I used version 1.1.1 of RedHat’s DocBook Import for Confluence to import the content back into Confluence, in a new space that I had created for this purpose.
  • There were a few hiccups, but basically it worked well.

A friendly word of warning: The DocBook Import plugin is unsupported. It was originally created for the JBoss Community Project Documentation Editor, and the developers decided to make it publicly available, free of charge. You can read about the plugin and ask questions on the JBoss Community site.

Exporting the content to DocBook XML

I used the Scroll Wiki DocBook Exporter, a Confluence plugin from K15t Software, to export the content of my book to DocBook XML. My earlier post gives quite a bit of detail on how to use the plugin: Writing a book with DocBook and a Confluence wiki. This screenshot shows the settings I used to export the pages from Confluence:

Exporting from Confluence to DocBook XML

A note: I had to use the template called “Book using preface and chapters“. When I chose the template “Book using preface, parts and appendix“, the import pulled in only the home page and the appendices. The explanation lies somewhere in the DocBook formatting, but I don’t know the details.

Importing the XML back into Confluence

I installed RedHat’s DocBook Import for Confluence plugin onto my Confluence site. Then I added a new space in Confluence, and went to the home page of that new space. The plugin adds an option to the “Tools” menu called “JBoss DocBook Importer“:

DocBook import option in Confluence Tools menu

Clicking that option invokes the importer configuration page:

DocBook Import configuration page

As we who know and love Confluence are aware, you cannot have two pages with the same name in a Confluence space. The DocBook Importer accepts a prefix that it will use to resolve such conflicts. But on my first attempt, I did not give it any prefix. I knew that all the page titles in my book were unique, so I thought the import would be good. It turned out that there was a duplicate page title, because I had used a heading level 1 to highlight the book title, and had given the page the same name as the title.

The importer gave me an error message, and I supplied a rather unimaginative prefix “123”.

Message requesting prefix to resolve duplicate page names

This time everything went smoothly. In the following screenshot, you can see the success reported by the importer on the right, and the newly-created table of contents in the left-hand panel:

Import successful

Results

Success!

  • All the pages are there, with all content present.
  • The images are all present.
  • Tables are correctly formatted. My content includes only simple tables.
  • List formatting looks good.
  • Bold and italic formatting are good.
  • Links are good.

One of the book's illustrations by Ryan Maddox

The above screenshot shows one of the illustrations in the book, created by Ryan Maddox and reproduced here with his permission.

A few hiccups

Some things will need fixing, either manually after each import or perhaps in a future version of the importer plugin:

  • The images are larger than on the original pages.
  • URLs printed on the page have acquired URL encoding rather than retaining the human-readable form.
  • The Scroll Wiki DocBook Exporter plugin allows you to add information for a book index and footnotes, via special macros. The reimported pages print the content of the index or footnote entry on the page itself. For example, in the screenshot below I have highlighted an index entry at the top of the page.

Another page imported from DocBook

Thanks to the teams at K15t Software, Red Hat and the JBoss Community for these two plugins!

Using the plugins in earnest

Richard Hamilton, at XML Press, and I have used the Scroll Wiki DocBook Exporter to produce my new book. I haven’t used the DocBook Import, other than to try it out for this blog post. I’d love to know if you’re using either of these two plugins in your documentation or content management procedures. Do you have any stories or tips to share?

Publishing documentation to ebooks from Confluence wiki

I’ve been having such fun over the last couple of days, playing with the Scroll Wiki EPUB Exporter. It is a plugin (add-on) for Confluence that converts wiki pages to EPUB format. What amazed me was how easy it is to create ebooks this way, and how very shiny they look on an iPad. A definite “ooh” moment.

The Scroll Wiki EPUB Exporter exports Confluence pages to an EPUB file. EPUB is an open ebook (electronic book) format developed and maintained by the International Digital Publishing Forum. EPUB supports reflowable content, meaning that the content’s layout changes to suit the device on which the content is being read. HTML is another example of a reflowable format. A growing number of devices support the EPUB format, including the iPhone, iPad, Android devices and a number of ebook readers and tablets.

I used the Scroll Wiki EPUB Exporter to convert the Bitbucket user’s guide from Confluence wiki to EPUB format. Then I pulled the EPUB file into the iBooks app on the iPad. Here’s what it looks like in iBooks:

Publishing documentation to ebooks from Confluence wiki

I’m a technical writer, so now I’ll show you how to do it. 🙂

Installing the EPUB exporter plugin

First I installed the EPUB plugin onto my test Confluence site. In case you’d like to try it out too, here’s a quick guide to installing a plugin into Confluence. You need Confluence system administrator permissions to do this:

  1. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install“.
  2. Type the name of the plugin (“Scroll Wiki EPUB Exporter”) into the search box and click “Search“.
  3. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
  4. Click “Install Now“.

Alternatively, download the plugin (it’s a JAR file) from the Atlassian Plugin Exchange and save it on your computer. Then go to the Confluence plugin installation page, as described above, and click “Upload Plugin” to upload and install the plugin JAR file manually.

Next I emailed the team at K15t Software (sales@k15t.com) asking for an evaluation licence. When it arrived, I installed the licence key onto my site. Here’s how:

  1. Choose “Browse” > “Confluence Admin“.
  2. Click “License” under “Scroll Wiki EPUB Exporter” at the bottom of the left-hand navigation panel.
  3. Paste the licence key into the text box.
  4. Click “Save“.

Ready to epublish!

Converting Confluence pages to EPUB

Once the Scroll Wiki EPUB Exporter is installed, there’s a new option in the Confluence “Tools” menu: “Export to EPUB“. Click it to see the export screen:

Publishing documentation to ebooks from Confluence wiki

Scroll Wiki EPUB Exporter options

The plugin produces a zipped file with a .epub extension. Next, I wanted to see the document on an ebook reader of some sort. There’s an iPad in the house, so let’s try that.

To get the file onto my iPad, I emailed the file to myself (well, actually to Peter, because the iPad is his). I opened the email message on the iPad, tapped the attached file and tapped “Open in iBooks“.

Publishing documentation to ebooks from Confluence wiki

Opening an EPUB file from email on the iPad

And voila, it’s as easy as that. Here’s another picture of the Bitbucket documentation open in iBooks on the iPad:

Publishing documentation to ebooks from Confluence wiki

Bitbucket documentation in iBooks on the iPad

iBooks is a built-in app (application) on Apple’s iPad 2. It is also available for download from the App Store.

Two things came to mind

While writing this post, two things struck me.

Firstly, I wanted to take a screencast so that I could post a video showing the page turning and other cool aspects of iBooks. There’s no way to make a screencast on the iPad! I would have had to make a video using a camera.

Secondly, I started thinking about the content itself. It’s great that we can now make ebooks so easily. Technically, the problem is solved. Write the content in Confluence then export it to EPUB and people can read it on all sorts of devices.

But we need to think about the actual content. People using ebooks will not necessarily want to click links that point to websites and the infamous “more information”. They may not even want a practical “how to” guide. In the case of the Bitbucket guide in particular, people on ebook readers probably will not be able to write any code or access their source repository to try out the steps. Instead, perhaps the content destined for an ebook should be more of an overview, introductory or inspirational nature.

Love the EPUB exporter plugin

The Scroll Wiki EPUB Exporter is in beta release at the moment. I’m sure the developers would love any feedback we want to give. Anyone can write a review on the plugin page. Congrats to the guys at K15t Software – consider my hat doffed!

Converting documents between a wiki and Word, XML, FrameMaker or other help formats

This week I published a post on the Atlassian blog about single source publishing on a wiki. I’m cross-posting it here because it may be useful to technical writers who read this blog. 🙂

The post discusses a few of the reasons why we may want to write our documents on a wiki and then publish them to other formats, or conversely write the documents using another tool and then publish them to a wiki as one of the delivery formats.

Next, the post recommends some good tools for converting content from these formats into Confluence wiki format:

  • From Microsoft Word to Confluence wiki
  • From Adobe FrameMaker to Confluence wiki
  • From DITA XML to Confluence wiki

And some tools for converting content from a Confluence wiki into these formats:

  • From Confluence to PDF
  • From Confluence to Microsoft Word
  • From Confluence to HTML
  • From Confluence to XML (Confluence-specific format)
  • From Confluence to DocBook XML
  • From Confluence to Eclipse Help
  • From Confluence to JavaHelp

In case it’s useful, there’s also a post I wrote a while ago about getting content into and out of wikis. That post looks at a couple of other wikis as well as Confluence, and covers a wider range of tools. The new post on the Atlassian blog is more up to date and is specifically about conversion tools to and from Confluence.

If you’re interested, mosey on over to the Atlassian blog and take a look. I’d love to hear your experiences with the tools mentioned in the blog post, or if you’ve used any other tools or need any other conversions. What did I miss out? There’s an interesting discussion going on already. Here’s the link again: Technical writing in a wiki – single source publishing.

AODC day 3 – Delivering documentation on a wiki

This week I attended the 2009 Australasian Online Documentation and Content conference (AODC) in Melbourne. On Friday, the third day of the conference, it was my turn to give a presentation.

My AODC presentation was about using a wiki for technical documentation. Here are the slides and supplementary material from my presentation:

I hope the slides with additional notes will be useful to the conference attendees, and maybe also to people who couldn’t make it to the conference this year.

Update November 2009: I wrote an article based on the presentation, which appears in the October 2009 edition of Southern Communicator. A PDF extract is available for download from this blog post.

Background to the presentation

Writing technical documentation on a wiki is what I do all day and what I’ve been doing for almost two years now. I’ve been a technical writer for more than ten years, using various tools and working in various businesses. I’ve enjoyed every authoring tool I’ve used, and wikis are no exception. There are difficult bits, of course. But there’s that satisfaction you get when you see your document displayed in an aesthetically pleasing and functionally useful way. Wikis do it differently, but the sense of delight is the same.

I’m a technical writer at Atlassian. We use Confluence wiki more or less “out of the box” to author, manage and publish our documentation. We don’t extend the wiki’s core functionality via plugins or other customisations (with a few exceptions). There are two reasons for this decision:

  • Atlassian follows the principle of “eating your own dogfood”. That means that you use your own products, so that you can feel your customers’ pain. And their pleasure 🙂
  • We make our documentation available as an XML download, so that other people can upload it as a wiki space on their own Confluence instances. If we used a number of plugins that are not a standard part of Confluence, then other people would not be able to use the documentation in this way unless they installed the same plugins.

So my presentation was about the features of the wiki that are especially useful in technical documentation, and the procedures you might put in place to work around the bits that the wiki doesn’t do for you. The main points I discussed are:

  • How a wiki is useful in agile development.
  • Workflow and tracking.
  • How to put some structure into wiki documentation.
  • Release management.
  • Steering wiki development — how we as technical writers can let wiki developers and plugin developers know what features we’d like in a wiki.

The content is similar to the talk I gave at WritersUA in Seattle, except that the AODC presentation was double the length (an hour instead of half an hour). So I was able to add some extra information and do more live demonstrations.

Breaking news not included in the notes

The presentation mentions the Scroll Wiki Exporter, that converts wiki markup to DocBook. In the last week K15t Software have released version 1.0 of Scroll, their first production release. See the Scroll web site and my blog post.

Scroll converts wiki to DocBook and PDF

K15t Software have just announced release 1.0 of Scroll, a Confluence plugin that converts wiki documentation to DocBook and PDF. I’ve been interested in this project since the early beta days and I’m excited for the K15t guys about the functionality Scroll offers already and about their plans for even more awesome developments.

First things first: You’re probably wondering why they’re called “K15t Software” 😉 It’s because one of the developers and company founders is Stefan Kleineikenscheidt. I guess that most people, like me, go cross-eyed upon encountering his surname. So he uses “K15t”, in the proud tradition of “i18n” and other such abbreviations. Another K15t Software developer is Tobias Anstett, fondly known as “t11t”. During Scroll’s beta period we’ve had some good conversations via Twitter, blogs, video conferencing and email.

History in the making

The guys founded K15t Software as a company just a few weeks ago. If you’re a technical writer, you’ll like their mission statement:

“K15t Software is a small development shop from Stuttgart, Germany. Its mission is to build useful software products with the focus on tools for wiki-based documentation.”

It all started five years ago, when Stefan lodged a request for a DocBook export from Confluence wiki. The request is on the Atlassian JIRA site — CONF-762. A DocBook exporter is not on the roadmap for core Confluence, so Stefan and the team decided to build one as a plugin. And the rest is history! Well, it’s the future too, because K15t plan to keep adding features to Scroll.

How does Scroll work?

It’s a plugin (add-on) to Confluence. If you have administrator permissions on your Confluence site, you can install the plugin as described in the Scroll Installation Guide.

Once it’s installed, the “Scroll Wiki Exporter” option will appear in your Confluence menu. Here’s a screenshot of the option in Confluence 2.10. I’m on a wiki page called the “Crowd User Guide” and have opened the “Tools” menu on the right:

Scroll converts wiki to DocBook and PDF

Scroll converts wiki to DocBook and PDF

When you choose the “Scroll Wiki Exporter” option, you get a screen with some tabs where you can choose either PDF or DocBook output and set some formatting options. On the “Document Information” tab you can set the document title, author and version. Scroll will provide default values based on the wiki page, but you can change them:

Scroll converts wiki to DocBook and PDF

Scroll converts wiki to DocBook and PDF

The “Page Tree” tab shows you a hierarchical view of the pages you are about to export. The top level of the tree is always the page you were on when you clicked the “Scroll Wiki Exporter” option. The export will include that page plus all its sub-pages and their sub-pages etc. At the moment, “Page Tree” tab is view only. Scroll may allow re-ordering in a future release.

Next is the “Formatting” tab. Here’s where you choose either PDF or DocBook. If you choose PDF, you can select a theme, language, etc. Scroll 1.0 has two themes available. In future releases, K15t Software plan to provide more themes and also more options for customisation.

Scroll converts wiki to DocBook and PDF

Scroll converts wiki to DocBook and PDF

The Scroll documentation tells you more about the formatting options.

On the “Advanced” tab, you can tell Scroll what to do if it encounters some wiki markup or macros that it doesn’t recognise.

Scroll exports wiki to DocBook and PDF

Scroll exports wiki to DocBook and PDF

When you’re ready, you kick off the export. Scroll will show its progress and then present you with a file for downloading.

Scroll exports wiki to DocBook and PDF

Scroll exports wiki to DocBook and PDF

If you chose to export as PDF, the output will be a PDF file. If you chose DocBook, it will be a zip file containing the DocBook 5 XML and all images and other attachments.

Some comments from me

I’ve really enjoyed my contact with Tobias and K15t. They’re passionate about their software, passionate about Confluence wiki, and keen to hear feedback. Here are some useful titbits from my experimenting with Scroll:

  • Note the {scroll-ignore} macro. You can put it onto your wiki page to tell Scroll not to export a particular chunk of text/content.
  • Scroll supports a number of wiki markup elements and macros. The Scroll Authoring Guide tells you how to write your text for best Scroll results.
  • Scroll exports DocBook version 5.0.
  • The “Scroll Quick Help” tips on the right of the export screens (see above) are useful and concise.
  • It’s really useful to be able to determine error handling, telling Scroll what to do when it encounters some wiki markup or a macro that it doesn’t know what to do with. See the “Advanced” tab described above.
  • In the PDF export, the “Simple Documentation” theme is neat and attractive.
  • For PDF, Scroll 1.0 has two themes available. In future releases, K15t Software plan to provide more themes and also more options for customisation. They’re also planning to allow pluggable themes, so that developers can create their own themes for Scroll.
  • I’ve suggested an addition to the Scroll documentation, to provide more information about the DocBook XML produced. The Scroll team have added this to their “to do” list.
  • The section on nesting of headings in the Scroll documentation explains why your heading levels may sometimes be different to what you expect.

Some comments from Giles

Giles Gaskell is a technical writer and colleague at Atlassian. He’s had extensive experience with DocBook, so he’s very interested in the Scroll plugin for Confluence too and I’ve been delighted to have his help with the plugin analysis. Here are Giles’s comments:

  • I really like the XML indenting that Scroll generates. It makes the XML output very readable via a standard text editor. I’ve worked with several XML editors in the past that force you to use their products to read/edit your XML content, since they either implement their own strange XML indenting or remove all white space > 1 character in length, in their XML output files.
  • It’s great that the version of DocBook XML exported by Scroll is 5.0. There are several processing advantages in DocBook XML 5.0 (via the RELAX NG schema) over what’s available in previous versions of DocBook XML (which are based on DTD schema only). Furthermore, it seems that RELAX NG is the way DocBook XML processing is headed.
  • I validated both DocBook XML exports using my own installation of jEdit and both were without any errors 🙂
  • Scroll does not add a document type declaration at the top of the XML output. It seems that DocBook XML 5.0 files which make use of RELAX NG-based processors typically do not possess a document type declaration. Likewise, it seems that DocBook XML 5.0 output without a document type declaration can only be processed by tools which are RELAX NG-compliant. Hence, it might be useful to have an option in the Scroll Wiki Exporter to add a document type declaration to the XML output, so that XML processing tools which verify XML against DTDs only can process these exports. [Giles would be very interested to hear any comments on this point from other DocBook users.]
  • It might also be worth providing an option to choose the version of DocBook XML exported — 4.0, 4.5 or 5.0. However, k15t might consider conducting a brief feasibility study on this first as I suspect integrating this feature would require a fair bit of work and some understanding about the differences between each version of DocBook. The main area of demand for this feature would be customers who have an existing/legacy tool setup that manipulates DocBook XML 4.x content, but do not have resources to upgrade their entire system to DocBook XML 5.0. DocBook XML 5.0 was only officially released in January 2008, so I suspect many DocBook XML customers would still be using DocBook XML 4.x.
  • Regarding the use of the <article> root element as opposed to <book> in the DocBook XML output: I believe this is an advantage, as it gives the author more flexibility to structure their books. The <book> element encapsulates information about a book’s content at a higher level than what is contained within an <article>. For example, an author may want to export multiple DocBook <article>s from a Confluence installation. These might be sourced from a variety of Confluence spaces or subtrees. They might then wish to combine these exported DocBook XML <article>s into a single DocBook <book>, using their own DocBook XML editor. If Scroll exported to a DocBook <book>, this would not be possible without additional XML processing.

Giles is also discussing a couple of minor points about the DocBook XML, such as the fact that each <link> element defines its own xlink namespace, and the production of the <?linebreak?> processing instructions.

Try it out yourself

You can either download the plugin for evaluation from the K15t Software site and try it on your own Confluence wiki, or you can use their demo Confluence site to see the pages already there, create your own pages, and then export them to DocBook or PDF. Awesome!

That’s all folks

Both Giles and I enjoy working with the K15t Software guys. They’re very quick to respond to feedback and I’m sure they’d be delighted for more input from other technical writers. 🙂

%d bloggers like this: