WebWorks ePublisher for converting documents to Confluence wiki

Over the past couple of weeks I’ve had the chance to experiment with WebWorks ePublisher, a set of tools that converts documents from Word, FrameMaker and DITA XML to a number of different output formats. One of those output formats is Confluence wiki. It’s been very interesting, so I thought I’d blog about it and see if anyone else wants to give it a go as well.

I started off knowing a bit about what ePublisher can do, having attended a WebEx demo. But I had never used it. This was such fun! Most of this blog post is going to look like a “how to” guide, because I’m hoping it will be useful to people who want to try this tool too.

A quick introduction to ePublisher

ePublisher is not a Confluence plugin. It is a set of standalone tools that can publish to Confluence as one of the output destinations. ePublisher allows you to transform content from Word, FrameMaker or PDF into a number of different output formats, including Confluence. It also provides a number of styling and design options for you to tailor the output documents.

These are the three components of ePublisher:

• ePublisher Pro – Use this component to design your “stationery” i.e. the appearance of the documents that ePublisher will output.
• ePublisher Express – Use this component to generate your documentation.
• ePublisher AutoMap – Use this component to automate the documentation generation process, and to perform batch processing, scheduling, etc.

The Evaluator Guide is in the form of a video tutorial.

Requirements

Because I wanted to convert my documents to Confluence wiki, here’s what I needed:

• Confluence version 2.10.2 or later. I’m using Confluence 3.0.
• Confluence remote API and XML RPC API enabled.
• The Content Formatting Macros plugin for Confluence, created and maintained by Adaptavist. This is a free plugin. You can install it directly from the Confluence administration console. (Instructions below.) The plugin is not officially supported by Atlassian, but is supported by Adaptavist.
• If your input documents are in Word or FrameMaker format, then you will need Word or FrameMaker installed on your machine. Supported formats are:
  • Microsoft Word 2000 to Microsoft Word 2007.
  • Adobe FrameMaker 6.0 to Adobe FrameMaker 8.0. I don’t have FrameMaker, so I didn’t try this out.
  • DITA XML 1.0 and 1.1.
  • In addition, for DITA input documents you will need the Java Development Kit (JDK) 1.4.2 or later. I have Sun JDK 1.6. You need this for Confluence too, so if you’ve already got Confluence you’re cool.

Install ePublisher and Confluence

Download WebWorks ePublisher and install it. I was using a full version of ePublisher, complete with all three components. If you’re looking for a trial version, you can try out the ePublisher Express part of the product for free.

Download Confluence and install it. You can get a free 30-day trial licence or a free personal licence.

Set up additional requirements in Confluence

1) Install the Content Formatting Macros plugin into Confluence. Step by step: Open the Confluence ‘Browse’ menu and select ‘Confluence Admin’. Click ‘Plugin Repository’ in the left-hand panel. Find the ‘Content Formatting Macros’ and click ‘Install’. Wait a while for the process to complete. It will eventually say “Installed” in the table next to the macro name.

2) Enable the remote API in Confluence. Step by step: Click ‘General Configuration’ in the left-hand panel of the Administration console. Click ‘Edit’ and click the ‘ON’ radio button next to ‘Remote API (XML-RPC & SOAP)’. Save the change.

3) Create the Confluence space where you want to put your documents. I gave my space a key of ‘TESTEPUB’. Note that you must create the space in Confluence before you deploy content to it via ePublisher.

Here’s my space:

ePublisher for converting documents to Confluence

Use ePublisher Pro to design the styles and format for your output documents

You will start off with a template created in the original software for your input document(s). For example, if your input documents are in Word, then you will import your Word template into ePublisher. If you also have input documents in FrameMaker then you will need a FrameMaker template to import into ePublisher.

Hint: For a quick start, if you don’t have a Word template you can just use the Word document you want to convert as your template. That’s what I did.

You will import your template(s) and/or sample document(s) into ePublisher Pro. ePublisher Pro will analyse the styles in the imported documents and provide you with a list of styles. You will then map the styles to your requirements for your output documents.

1. Open ePublisher Pro and create a new project. When you create the project, you will also define the output target. Because I wanted to create Confluence wiki pages, I selected “Wiki – Confluence” as my target. (You can add other targets later too, via the “Manage Targets” menu option.)

ePublisher for converting documents to Confluence

2. Add your templates or sample documents to the new project. You can do this as part of the create-project procedure. Or you can do it afterwards, by clicking ‘Project’, ‘Add Document’.

ePublisher for converting documents to Confluence

3. ePublisher Pro will scan your documents and extract all the styles, putting them into your new project.

4. Now you can map the styles from the input documents to the styles you want for your output documents. In ePublisher Pro, click the ‘Style Designer’ icon in the top tool bar. (When you move your mouse over the tool bar icons, a prompt appears in the status bar at the bottom to tell you what the icons mean.)

5. You will see a list of the styles extracted from your input documents, categorised into groups like paragraph styles, character styles, table styles etc. You can also add new styles, by clicking the ‘New Style’ icon (a tick mark) in the styles toolbar.

For each style, there are two tabs: the ‘Properties’ tab and the ‘Options’ tab. This is where you can determine your output styles, and also things like page breaks via ‘Page Break Priority’ (e.g. start a new page for each heading level 1) and table of contents levels.

ePublisher for converting documents to Confluence

ePublisher for converting documents to Confluence

6. Save your style definitions by choosing ‘File’, ‘Save as Stationery’.

ePublisher for converting documents to Confluence

That’s the ePublisher Pro part of the process done, i.e. the design work that will often be done by specialised designers. Now you can put on your document publisher hat and start converting your documents.

Use ePublisher Express to convert your input documents to the chosen output format(s)

1) Start ePublisher Express.

2) Create a new Express project. When it prompts you for stationery, select the stationery that you created from your input document templates earlier.

ePublisher for converting documents to Confluence

3) Add your input documents. You can do this while creating the project, or later via ‘Project’, ‘Add Document’. I did it by dragging the documents from my Windows file explorer into the ePublisher Express window.

Hint: When dragging and dropping, you need to drop the documents directly into the folder in the Express ‘Document Manager’ panel, not just into the panel itself.

ePublisher for converting documents to Confluence

I added a number of Word documents, and also a DITA document just for fun. I used the DITA sample document from project Gutenbert: 20,000 Leagues Under the Sea by Jules Verne. I simply dragged the ‘ditamap’ file into my ePublisher Express project. Here’s the result:

ePublisher for converting documents to Confluence

4) Next I needed to tell ePublisher Express what output format I wanted. I did this by adding a ‘Deployment Target’. Step by step: Click the ‘Target Settings’ icon in the ePublisher Express toolbar, then click ‘Add deploy target’, then ‘Add’. Select ‘Wiki – Confluence’ then ‘Edit Configuration’. A popup dialogue now asks you for the location of your Confluence site and the space key. This is the wiki space where your documents will end up. I entered the URL of my Confluence wiki (http://localhost:8080) and my space key (TESTEPUB):

ePublisher for converting documents to Confluence

After adding the new deployment target, I selected the Confluence target in the ‘Deploy to’ field as well:

ePublisher for converting documents to Confluence

5) Now for the fun part! 🙂 I clicked the ‘Generate All’ icon in the ePublisher Express toolbar. Sure enough, the generation process started:

ePublisher for converting documents to Confluence

6) Antici… pation!Excitement! I kept flipping between my ePublisher window and my Confluence screen, to see the wiki pages appear.

Duh! This is where Sarah calls herself a “banana”.

I hadn’t realised that there’s another step required if you are publishing your content to a wiki. The generation process produces the output files, containing wiki markup, CSS and your text. Then you need to deploy the content to the wiki. I tried various configurations, then gave up and called WebWorks for support. That support WebEx session must be the shortest in history. 🙂

7) Deploy your content to the target — In ePublisher Express, click ‘Target’ then ‘Deploy’:

ePublisher for converting documents to Confluence

8) Yippee! My pages appeared in Confluence. If you leave all the design settings at their defaults, as I did, then you get a table of contents page and some neat navigation buttons at the top of every page. Here’s the automatically-generated table of contents page:

ePublisher for converting documents to Confluence

For my quick and dirty experiment, I exported some of the Crowd documentation pages from Confluence to Word, then pushed them through ePublisher to put them back into Confluence. Here’s one of the resulting pages back in Confluence:

ePublisher for converting documents to Confluence

And here’s a page from the Jules Verne DITA document, in the same Confluence space:

ePublisher for converting documents to Confluence

What happens when you update or comment on wiki pages?

After deploying my pages to Confluence, I updated a page in Confluence and also added a comment to the page. Then I redeployed the content from ePublisher.

When you deploy your content from ePublisher, it updates any existing pages with the content from the ePublisher source document. In effect, if you have updated the page in Confluence, your change will be overwritten by the ePublisher deployment. The page history retains every version of the page. The comments on the wiki page remain untouched. (This is as you would expect, because ePublisher uses the Confluence API to apply the updates.)

There is no “round trip” option available, i.e. you can’t update the pages in the wiki and then export the updates back to your source documents via ePublisher. The tool is intended for people who use Word, FrameMaker or DITA as their primary authoring environment, or people who want to convert their documents to wiki format permanently.

Conclusion

This was a rough-and-ready test, because I didn’t have time to set up my own templates or design stationery to make my output pretty. Even so, it was easy to push my Word and DITA documents through to Confluence and to produce a wiki documentation set that has a consistent format and navigation. Apart from my “banana” moment, the process was quick and painless.

I’d like to spend more time exploring the setup of the templates and of the stationery, to see how I can refine the output and tailor the Confluence pages to a specific style. Just examining the options available in ePublisher shows that it has a lot to offer in this respect. Alas, I don’t have time right now, and I wanted to blog about how far I’ve got without waiting til I do have time.

I’d also like to explore ePublisher AutoMap, which lets you automate the generation and deployment processes. This means that you can schedule batch jobs to tackle large volumes of documentation and to do the conversion on a regular basis.

I hope the above step-by-step guide through my experiment will be useful to anyone who wants to try ePublisher with Confluence. This tool will be very useful to people who have a large set of legacy documents that they want to convert to wiki format, or people who want to author their content outside the wiki on an ongoing basis, and convert it regularly to wiki as well as other formats. Single-sourcing of content is great for environments where different readers or customers need their documentation in different formats.

More information

WebWorks are holding a Round Up ’09 conference in Austin on 19-21 October. There’s sure to be lots of information there, about using and publishing to wikis, social documentation and other interesting stuff. Wish I could be there too!

Bill Arconati wrote a post on the Atlassian blog, describing the demo the WebWorks guys gave us, including a video of the session.

Let me know if you decide to give it a go, and whether the step-by-step guide above was useful. If you get further into the templates, stationery and AutoMap side of things before I do, I’d love to hear your experiences too.

ePublisher Pro – Use this component to design your “stationery” i.e. the appearance of the documents that ePublisher will output.

ePublisher Express – Use this component to generate your documentation.

ePublisher AutoMap – Use this component to automate the documentation generation process, and to perform batch processing, scheduling, etc.

I found the online help shipped with the product more useful than the online documentation. Start ePublisher Pro and click ‘Help” to open the local help system in your browser.