A Confluence-to-XML export engine in the making
Imagine if you could use a wiki’s editing and collaboration tools to create your documentation, and then export your complete documentation set to a recognised XML format such as DocBook or DITA. From the XML, you could use your existing tools to transform the documentation to the various formats required by your different audiences or put it through your normal publication and archival workflow.
K15t & Friends are working on the Scroll Wiki Exporter, which exports Confluence wiki spaces and pages to DocBook and PDF. I’ve tried the beta DR03 version of the product and I think it has a lot of potential.
A friendly note of warning: The Scroll Wiki Exporter is currently in beta release. It is a Confluence plugin, developed by a third party. It is not part of the core Atlassian Confluence product. If you want to try it out, you should install the plugin into a test installation of Confluence.
Scroll Wiki Exporter is a Confluence plugin that converts a set of wiki pages to DocBook or PDF. You can choose to export an entire space or any page tree (hierarchical set of documents) within a space.
Screenshot after installation of the beta plugin, showing the Scroll Wiki Exporter option in the Confluence Tools menu and Scroll’s Export Options page:
What can it do right now?
The software is in an early beta phase, so there are still some limitations on what it can do. The Scroll development team are adding new capabilities with each new beta release.
Scroll Wiki Exporter converts Confluence wiki spaces and pages to DocBook and PDF. Confluence itself supports a number of formatting options and macros. When you run Scroll Wiki Exporter, it analyses the wiki pages and displays warnings of any formatting it will not be able to reproduce. You can choose to ignore the warnings and do the export anyway. The beta version is best used with Confluence 2.8.2. The Scroll team will be working on compatibility with other versions for a future release.
For those participating in the beta testing, the Scroll team have provided some excellent documentation. It is clear and well structured, simple and to the point.
The documentation is itself written on Confluence and then converted to PDF using Scroll Wiki Exporter. It is also provided as the sample content (i.e. a Confluence space) for beta testers to use when testing the software. Multi-purpose documentation at its best 🙂 There are a few grammatical errors, but basically the team have provided a very solid guide to getting Scroll Wiki Exporter up and running.
I’ve used the Scroll Wiki Exporter to generate PDF and DocBook outputs, using the sample space provided with the beta documentation. The DocBook output passes XML validation, and the PDF output looks good. I have also tried the Scroll Wiki Exporter with the Crowd documentation space, but there were a few hiccups because of the formatting and macros used in that space.
Some interesting aspects
Scroll Wiki Exporter allows you to choose a theme for your generated PDF or XML. The beta version I tried has only the default and Scroll themes. But the idea is that you will be able to add your own themes, defined in FOP (Formatting Objects Processor).
You can also choose to export a whole space, or a page tree starting from a selected page. At the moment, Scroll Wiki Exporter hooks into Confluence’s own page tree functionality. So when you re-arrange pages in the tree, you are actually re-arranging them in the Confluence space too. In a future release, there will be an independent means of organising pages just for the export.
Because I don’t use DocBook in my day-to-day documentation procedures, it was not easy to put the generated XML through its paces. It would be great if other technical writers can try it out too.
Scroll’s plans for the future
The Scroll team intend to provide conversion to DITA in a future release. At the moment, they are refining the DocBook capabilities. Once the framework is well established, they say, it will not be difficult to produce other formats such as DITA.
Calling tech writers
As someone who is enthusiastic about technical documentation on a wiki, I think the Scroll Wiki Exporter is a great initiative. The ability to export Confluence documents to a recognised XML format is a much-requested feature. See the existing requests for DocBook (CONF-762) and DITA (CONF-5571) support. This requirement also comes up often in forums, interviews and technical documentation conferences.
Technical writers may want to keep an eye on this one. The Scroll team will be issuing a public beta release within the next couple of months. Especially if you are already using DocBook in your day-to-day documentation procedures, your feedback would be really useful to the Scroll team. Let’s jump in there and give them as much feedback as we can. And I’d be very interested in your comments too:)
Posted on 17 September 2008, in atlassian, Confluence, technical writing, wiki, xml and tagged Confluence, DITA, DocBook, Scroll, Scroll Wiki Exporter, technical documentation, technical writing, wiki, wikis. Bookmark the permalink. 7 Comments.