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.