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:

• Slides with supplementary notes
• Slides only

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

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

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

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

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

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. 🙂

Update – Playing some more with DITA2Confluence

This is a quick update on my previous blog post about DITA2Confluence. I have just uploaded an extract from the Encyclopaedia Britannica, provided by Project Gutenberg, to my Confluence site. Fun!

All I had to do was download the sample Encyclopaedia Britannica DITA files, create a properties file telling DITA2Confluence where it could find them, and then run the Ant command.

Update - Playing some more with DITA2Confluence

Here’s the table of contents in Confluence:

Update - Playing some more with DITA2Confluence

There were a few errors, but basically it worked.

Playing with DITA2Confluence

Lisa Dyer has recently announced the latest version of the DITA2Confluence tool for  converting DITA XML to Confluence wiki pages. It’s part of DITA2wiki, an open source project on SourceForge. I found it via Anne Gentle’s excellent overview. Thank you Anne and Lisa! So I’ve been playing with it. It’s very very cool.

I downloaded the DITA2Confluence binary and used it to import the sample documentation set, which also happens to be the user guide for the tool. I thought it might be useful for others to see the steps I followed. I’m using Windows Vista and Confluence 2.9.

From this:

Playing with DITA2Confluence

To this:

Playing with DITA2Confluence

Basic Setup

First, install and set up all the bits and pieces:

1. Download an evaluation version of Confluence. (I used the Standalone ZIP archive, but you can use the automated installer. Click “Show All” near the top right of the installation page to see the download file for the automated installer.)
2. If you’re using the ZIP file, unzip it to a folder of your choice.
3. If you’re using the ZIP file, navigate to <<your chosen unzip folder>>\confluence-2.9-std\confluence\WEB-INF\classes and open the confluence-init.properties file in a text editor. (Notepad will do.) Set a location for your Confluence home directory. This is where Confluence will store its data. You can just choose the default location by removing the # sign in the last line of the file. Confluence will create this folder on startup if it doesn’t exist yet. Save the properties file.
4. I already had Java 6, and had set my JAVA_HOME variable. If you’re using the ZIP file and you haven’t got Java 5 or 6 yet, you’ll need to download and install Java and set JAVA_HOME. (There’s more on setting environment variables in a step below.)
5. Start Confluence by navigating to <<your chosen unzip folder>>\confluence-2.9-std/bin and running startup.bat.
6. Start your web browser and go to http://localhost:8080. You should see the Confluence setup wizard.
7. Follow the instructions to set up Confluence. Choose the default installation. It will ask you to specify a username and password for the administrator. To make things easy, just choose a username of “admin” and a password of “admin” 🙂
8. Download the DITA2Confluence “binary” and unzip it into a folder somewhere.
9. Navigate to the folder where you unzipped DITA2Confluence and open the confluence.login.properties file in a text editor. (Notepad will do.)
10. Check the URLs in the file. They tell the tool where to find Confluence on your machine. If you didn’t change any of the defaults when installing Confluence, then these URLs will be fine.
11. Check the user and password in the file. The tool will use these credentials to log in to your Confluence instance. If you set your administrator username and password to “admin/admin” when installing Confluence, then there’s no need to change them here. If you chose some other username and password, change them in this file. Save the file.
12. In the same folder, take a look at the dita2wiki.guide.properties file. I didn’t need to change anything in this file. It points to the location of the sample documentation set which you’ll import into Confluence. The DITA2Confluence User Guide tells you more about it. (See the PDF file included in the download.)
13. Download Ant and unzip it somewhere. I just chose the straight zip archive (apache-ant-1.7.1-bin.zip).
14. Now you’ll need to edit your Windows environment variables, to add Ant to your path and to set up ANT_HOME. In Windows Vista, go to “Start” –> “Control Panel” –> “System”. Click “Advanced System Settings”. Assure Vista that yes, you really did mean to do this. Click the “Advanced” tab. Click the “Environment Variables” button.
15. Under “System Variables”, select “Path” and click the “Edit” button. Now it’s easiest to copy all the text that’s there and paste it into Notepad for easier editing. Add a semi-colon to the end of the string, then paste the address of your Ant bin folder. Then paste the entire text string back into the environment variable and click “OK”. So my path looks like this now: %SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;C:\Program Files\Microsoft SQL Server\90\Tools\binn\;C:\Program Files\ATI Technologies\ATI.ACE\Core-Static;C:\PROGRA~1\ULTRAE~1;C:\Program Files\QuickTime\QTSystem\;D:\Ant\apache-ant-1.7.1\bin
16. Still under “System Variables”, click “New”. Add a variable called “ANT_HOME”  and paste the address of your Ant unzip folder. Mine is:  D:\Ant\apache-ant-1.7.1

That’s the basic setup done. You can run the DITA2Confluence tool now, and it will happily import the sample content into Confluence, creating a brand new space with a number of pages. I did this, just to see what it would look like. The only issue is that a couple of plugins are missing. So your pages will have some pink banners saying that Confluence could not find the {multi-excerpt-include} macro and the {set-sort-id} macro.

A couple of Confluence plugins

My understanding is that it’s quite possible to design DITA documentation sets that don’t invoke these macros and therefore don’t require the two extra plugins. You’ll need them because you’ll be importing the sample documentation, which does ask for the macros.

So let’s install the plugins into Confluence first, in case you don’t like pretty pink error messages 😉

1. In your browser, make sure you have Confluence open (at http://localhost:8080) and that you are logged in as the admin user.
2. Let’s do the Adaptavist Builder Theme plugin first. In Confluence, go to the “Browse” menu and select “Confluence Admin”. Click “Plugin Repository” in the left-hand navigation panel. The page will take a while to load. When it’s finished, search the page for “Builder Theme” and click the “Install” link next to it. This will also take a while. When it’s finished, the page will re-load and the word “Installed” will appear next to the “Builder Theme”. This is the Theme Builder plugin from Adaptavist, and they kindly allow you to use an evaluation version while you are evaluating Confluence. (BTW, if your Plugin Repository is giving problems, you can install the plugin directly from the jar. We’re about to do that for another plugin, and the Adaptavist docs tell you where to find their jar.)
3. Now let’s do the Multi-Excerpt Plugin. The jar for this one is included in your DITA2Confluence download. In Confluence, still in Confluence Admin, click “Plugins” in the left-hand navigation panel. Click the “Browse” button and navigate to the folder where you unzipped DITA2Confluence. Open the “lib” folder and select the file called “multiexcerpt-plugin-2.0.jar”. Click the “Upload” button to upload the file into the Confluence plugins. The Multi-Excerpt Plugin is from Artemis Software, and you can use an evaluation version of this one too.
4. All done.

Running the DITA-to-Confluence conversion tool

Now for the fun bit. Your Confluence site will magically acquire the DITA2Confluence user guide in its own Confluence space:

1. Make sure Confluence is running.
2. In Windows, open the command-line interface. (In Vista, go to “Start” –> “Run” then type “cmd” and click “OK”.)
3. Navigate to the folder where you unzipped DITA2Confluence. (This is where the “build.xml” file resides.)
4. Run the Ant command: ant -Dguide.file=dita2wiki.guide.properties
5. Done!

In Confluence, you should now see the new content. Go to your Confluence Dashboard, and check to see if the “dita2confluence” space has appeared. Click through to the space and its pages to see the nifty new content.

In conclusion

This is a very exciting new tool, and it’s awesome that it’s open source. Good on ya, Lisa and friends.

At the moment, the tool allows you to convert content from DITA to Confluence. It doesn’t yet allow you to convert from Confluence to DITA. Two things are relevant here:

• Lisa is calling for help with the round-trip DITA-Confluence-DITA conversion.
• There’s another Confluence plugin under development, called Scroll Wiki Exporter, which I’ve blogged about before. It converts from Confluence to DocBook XML, and there are plans to add DITA soon.

At this stage, I haven’t done much more than try out the tool, import the sample content and write this rather lengthy blog post 😉 But I’m totally enamoured of the possibilities this tool exposes, for including Confluence import/export into the overall documentation management process and for providing output in the many different media types which different readers require.

Wikis bring indisputable benefits in terms of collaboration on content, working in an agile environment, and involving the whole organisation/community in ownership of the documentation. Up to now, wikis have not been so strong on the document management and release management side of things. The wiki-DITA-wiki tools are an excellent way of filling this gap.