My new book is available on Amazon and Barnes & Noble

Newsflash: My new book is now available at Amazon.com and Barnes & Noble. The book is titled, Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It is about developing documentation on a wiki. It’s also about technical communicators. And chocolate.

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?

Pre-orders of my book available at reduced price

If you’re thinking of buying my book, now is a very good time. Pre-ordering is available at Barnes & Noble, and they’re offering a price of just $26.96 (reduced from $39.95) for a few days.

Update (Saturday 5:15pm in Sydney): The price is now $21.57! I don’t know how long the offer lasts.

Update (Sunday 19 February): There are some problems with the Barnes & Noble page for the book – there is currently no pre-order or buy button at all. In addition, some people have received messages from B&N saying that their orders have been cancelled. Richard Hamilton at XML Press  is investigating. I’m so sorry about the confusion. I’ll let you know as soon as I hear more.

Thanks for letting me know about the problem. I hope it is sorted out quickly.

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. It’s about wikis, Confluence, technical communication, technical writers, and of course chocolate.

Follow Ganache, technical communicator extraordinaire, inside Confluence wiki for an in-depth guide to developing and publishing technical documentation on a wiki. Then, with the groundwork done, you will see how to make your wiki fly.

Experience life as a wiki author and reader. Working in an agile environment? Wikis were made for that! Wondering about search engine optimization (SEO)? Wikis can do that too. Learn how to harness the wiki’s social and collaborative features, turning technical documentation into true communication.

The book is also the confluence of technical communication and chocolate. Because you can’t have one without the other!

I hope you enjoy it.

Details

Pre-order at Barnes & Noble: http://www.barnesandnoble.com/w/confluence-tech-comm-and-chocolate-sarah-maddox/1038398637?ean=9781937434007

More details of the book at XML Press.

Translating documentation developed on Confluence wiki

A few people have asked me recently about translating content into other languages, and what functionality Confluence provides to help that process. This post is a summary of what I know, in the hope that it will give people pointers to follow up on. It’s also an invitation to share what you know about translating technical documentation.

We don’t translate our own documentation yet, so this post is based on conversations with people who need to translate their documentation, on my subsequent investigations, and on a couple of presentations I’ve attended. The presentations focused on content translation in general, and had nothing to do with Confluence.

If you’d like to add information about the requirements and process of getting documentation translated, please comment on this post. I’d love to know more about this area of technical writing.

Getting the documentation to a translation company

Translation companies need the documentation in a specific format. For example, some companies work with Microsoft Word, others with XML. So you’ll need to find out what formats work best for them, and then check if you can convert your Confluence content to that format.

Using core Confluence (that is, without adding any plugins) you can export your content to

• A proprietary XML format – useful for backing up your content and for transferring content from one Confluence site to another.
• PDF.
• HTML.
• Microsoft Word –a basic single-page conversion done via HTML and CSS.

The Confluence documentation has the details.

Plugins provide additional export formats:

• A more flexible export to Microsoft Word via Scroll Office.
• More PDF options via Scroll Wiki PDF Exporter.
• Export to DocBook XML via Scroll Wiki DocBook Exporter.

Getting translated content back into Confluence

You may want to provide the translated content on a Confluence site, as well as the original-language content. In some scenarios, you may want to do the following:

1. Send the initial English content for translation. (Let’s assume the original language is English.)
2. Upload the translated content into a Confluence space.
3. Update the English content for the next product release.
4. Send the updated English content for translation.
5. Also include a copy of the current version of the translated content, for updating by the translators.
6. Load the new version of the translated content into Confluence.

Looking at steps 1 and 2: When sending the English content to the translators, it would be best to send the Confluence XML, so that you can retain the formatting and macros that are part of your content. Then you can upload the translated content into Confluence without having to reapply the formatting and macros.

Looking at steps 5 and 6:  If you need to put the new version of the translated content back into Confluence, then the only available option is to use Confluence’s proprietary XML format. These are the steps to follow:

• Export the current version of the translated content from Confluence to XML.
• Send it to the translators and ask them to update the content embedded in the XML.
• Import the updated XML back into the wiki.

Getting rid of page history in the Confluence XML export

The problem with the current XML export is that it includes all the page history, so it is difficult to isolate the current content from the previous versions of the pages. This is troublesome when you are sending your original-language content to the translation company, because the content will probably have been through multiple reviews and releases. Each page will therefore have many versions.

There are two rays of hope here:

• One of the awesome Confluence developers is working on an update which will allow you to exclude page history when doing the XML export. I don’t know yet when this feature will be available, although I have promised him chocolate if he gets it into a release soon.
• A suggestion: You can use the Copy Space plugin to copy your content to a different space. This will exclude all page history. Then you can do the XML export from the new space. Note that the space key will be different too.

Optimising your content for translation

Here are a couple of references about optimising your content for tranlsation. They discuss content in general, not specifically Confluence-based content .

• A while ago I attended an excellent presentation by Sarah Forget. I blogged about it here: ASTC-NSW day 2: Preparing your documentation for translation.
• Cherryleaf recently published an interview with Jill Fifoot of Lloyd International: Translating and localizing documents – Cherryleaf interview with Lloyd International

Content reuse

One aspect of optimising your content is to employ content reuse. This helps to ensure consistency of terminology, which makes translation easier and the results more reliable. Content reuse can also reduce the number of words to be translated, thus reducing translation costs. In Confluence, you can use the include and the excerpt include macros to reuse content across pages. I’ve written a few posts about content reuse which may be useful.

Any more?

Over to you.