ffeathers — a technical writer’s blog

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.

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.

Over the last few weeks, I’ve been working on the guides for developers who write plugins (add-ons) for Confluence, Crowd and other Atlassian applications. This has been very interesting for a number of reasons: integration across different software applications, which translates to cross-application documentation too; content re-use while retaining the simplicity of individual guides for each application; developer documentation rather than user and administration guides; and last but not least, all the fun of an agile environment. And a wiki.

What’s a plugin?

A plugin is an add-on to an application, much like the bits and pieces you can add to your browser. People can write plugins to extend the functionality of Confluence, JIRA, etc. For example, you might write a plugin that adds a “Hallo” option to the Confluence “Tools” menu and displays “Hallo world” when clicked. Once you have written your plugin, you can make it available to other people too, by putting it into a common repository. There are a number of great plugins which provide some very cool functionality to Atlassian’s various applications.

What’s integration?

Atlassian is moving towards wider and more intimate integration between the different applications we develop. You can already do things like display a dynamic list of JIRA issues on a Confluence page, or display FishEye repository information on a JIRA page. Now the plan is to make the applications work even more closely together.

Developing a common plugin framework is one of the big parts of the move towards even deeper integration, because the plugin framework will help developers (both Atlassians and others) to write plugins that work on more than one of the products, and it will also allow plugins on each product to have a consistent look and behaviour from a user’s point of view, even when the plugin works on only one application.

How does this affect the documentation?

As is so often the case, the architecture of the applications affects the architecture of the supporting documentation. We needed a documentation system to cater for developers who want to write cross-application plugins. So they need to know the full details of the common plugin framework. But we also needed to cater for people wanting to write a simple plugin for just one of the applications. Those people don’t necessarily need or want to know that there’s a singing and dancing plugin framework behind the scenes. They just want to know how get their plugin up and running as easily as possible.

We also needed to ensure that common information is held in one place only, even though it may be used in multiple places. This is an excellent example where content re-use is essential and neatly matches the product architecture.

Why is it fun and agile?

Writing developer documentation is an essentially cerebral experience The main reason is that we technical writers don’t really have the time to actually test out this sort of documentation. When writing a user guide, administration guide or installation guide, we actually do the stuff and then write how it’s done. But with developer documentation, we rely more on input from the developers and architects, and then we organise the information into a cohesive documentation set. So I had the opportunity to draw some pretty pictures and to work on a purely intellectual basis, organising information without any UI in between.

The agile development aspect of it is also fun. We’re developing the plugin framework in phases, and slotting it into the various applications as and when they’re ready to receive it. So our design must allow the documentation for one application to grab content from a specific version of the plugin framework documentation. More than that, different versions of the same application will grab content from different versions of the plugin framework documentation. There are people out there using various historical versions of the applications at any one point in time, and they need the correct version of the documentation too.

And all of this on a wiki

What’s the plan and where are the pretty pictures?

By the way, I drew these diagrams on Confluence, using the Gliffy plugin. Then I exported them as jpeg images, later converted to png, so that I could include them on this blog post. Gliffy is one example of a great Confluence plugin, created and sold by a company other than Atlassian.

Here’s the design for the first release of application documentation which incorporates the common plugin framework documentation. Each box in the diagram below represents a documentation space on our Confluence wiki.

Cross-application plugins and their documentation

We use spaces as the version-control mechanism for the documentation.

The content in the plugin framework spaces is designed to be re-usable. The re-usable chunks are contained in a page hierarchy called an “inclusions library” and given a page name starting with an underscore, so that people see instantly that they’re special.

The application-specific documentation will dynamically include content from the plugin framework spaces using the {include} macro. In some cases, we may just link to the plugin framework documentation instead.

So here’s the way things may look some time early in 2009. This is just the documentation design, not a forecast of the actual application versions involved. It shows how we’ll have multiple documentation spaces in Confluence, for the plugin framework and for the applications. The arrowed lines show how each application version will pull in content (via Confluence {include} macros) from a specific version of the plugin framework documentation spaces.

Cross-application plugins and their documentation

Want to see it working?

It’s all happening.

We have the Plugin Framework 2.0 documentation in one space, and the about-to-become Plugin Framework 2.1 documentation in another space. (It’s undergoing metamorphosis at this very moment, awaiting the release of the next version of the framework.)

Crowd 1.5 supports version 2.0 of the Atlassian Plugin Framework. The Crowd plugin documentation now grabs and displays the correct version of the plugin module types. If you’re interested, you can take a look at these pages, to see the {include} macros in action. You can view the Wiki Markup code by clicking “Tools” –> “View Wiki Markup”:

• Web Item Plugin Modules
• Servlet Plugin Modules

What about hiccoughs?

Hiccoughs? On a wiki? Never! But I did find a few things to be aware of:

• If you want to dynamically include content across spaces, you must use the {include} macro — the {excerpt-include} macro does not work across different spaces.
• The above fact means that all pages your inclusions library must take into account that the entire content is dumped into the middle of another page. So the pages should not contain “related topics” or {toc} or other context-related data.
• We need to hard-code the space key into the {include} macros. For example, all the {include}s in the Crowd pages start with {include:PLUGINFRAMEWORK20:_Page Name}. So when Crowd moves to the next version of the plugin framework, we’ll need to manually change all these references to something like PLUGINFRAMEWORK21. This is a known limitation of Confluence macros.
• The search does not pick up the content when ‘included’. To solve this, we’ll need to add labels to the pages to ensure the most relevant data is picked up by search.
• There was a slight caching oddity when I used the Copy Space plugin (another great plugin, by the way) to create the version archive for PLUGINFRAMEWORK20. I had to manually refresh the pages to ensure that the ‘included’ content showed up properly in the Crowd docs. I’ll keep an eye on this.

Next up is Confluence 2.10, still under development. Other applications will follow. So there’s lots more fun in store for the Atlassian tech writers