Category Archives: Confluence
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:
- Send the initial English content for translation. (Let’s assume the original language is English.)
- Upload the translated content into a Confluence space.
- Update the English content for the next product release.
- Send the updated English content for translation.
- Also include a copy of the current version of the translated content, for updating by the translators.
- 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. 🙂
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.
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:
- Alan J. Porter – Writer, speaker, consultant
- Anne Gentle – Technical writer for OpenStack
- Ellen Feaheny – CEO of AppFusions
- Mark Fidelman – Social business GM at harmon.ie
- Robert Rhyne Armstrong – Director of documentation for RouteMatch Inc
- Sherif Mansour – Technical product manager at Atlassian
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:
- Log in as a Confluence system administrator.
- Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
- Type “scroll wiki docbook exporter” into the search box and click “Search”.
- Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
- 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.
- 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.
- Click “Tools” > “Export to DocBook”.
- Adjust the options in the dialog that pops up:
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:
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” xmlns:xlink=”http://www.w3.org/1999/xlink” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd” 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!
Guess a name to win a copy of my book
Would you like to have some fun, and perhaps win a copy of my upcoming book too? Just guess the name of the girl on the cover! The first person to get it right will receive a free copy of the book, in a choice of paperback or ebook format.
The book is all about using a wiki for technical communication. It’s called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinare for technical communication. It will be published in February by Richard Hamilton at XML Press.
The book cover
I love the illustrations in the book, and especially the picture on the cover. They are the work of a talented artist named Ryan Maddox.
Who is the girl on the cover?
She is the hero of the book. She is a technical communicator extraordinaire. Let’s dub her X for now. When you read the book, you will follow X as she sets up a Confluence wiki and adds a technical documentation space. Learn from her expertise with the wiki editor and macros. Share her adventures in agile development and search engine optimisation. Grow wings, as X does, and make your wiki documentation fly. Discover why X says we need a “kiss my wiki” attitude.
Guess her name – one guess per comment, guess as often as you like
What is X’s real name? Add your guesses as comments on this blog post. It’s just her first name, one word, that you’re looking for. You can add as many comments as you like, and write whatever you like in the comment, but please put only one suggested name per comment.
The first person to get it right wins a free copy of the book. You can choose whether you want a printed book (paperback), a Kindle version or an EPUB version.
If no-one has guessed the right name in the next few days, I’ll add a hint.
Let the fun begin. 🙂
Another chance to win
Here’s another opportunity to win a free copy of the book: Head on over to XML Press and sign up for email notification about the book. Your name will be automatically entered into a draw for a free copy.
Hint: Think chocolate
Here’s a clue: Our hero’s name has something to do with chocolate.
Keep guessing. 🙂 I’ll add another clue soon!
(Hint added on Sunday 15 January, early morning Sydney time.)
We have a winner!
The name of the girl on the cover is… Ganache. Congratulations to Jill Brockmann on guessing the name and winning a free copy of the book!
So, Ganache is the name of our our technical communicator extraordinaire. But this may be the first time ever that the word is used as a person’s or character’s name. Ganache is also a mixture of chocolate and cream, used to fill chocolates or cakes. People often add a flavour to the mixture, such as chopped raspberries to make a raspberry ganache.
Thank you to everyone for taking part. I hope you’ve had as much fun as I have!
(Winner announced on Sunday 15 January, 6pm Sydney time.)
ffeathers 