This post is the fifth in a series from Atlassian’s technical writing team about using a wiki for technical documentation. Last week Rosie Jameson wrote about managing documentation releases. In this post, I’ll cover single source publishing on a wiki.
As technical writers, we always keep our readers’ and customers’ needs at the forefront of our minds. One of the most basic requirements is that our readers will have access to the documentation. No matter what tool we use to write the documents, we must be able to publish them in various output formats depending on where our readers are and the tools they have at their disposal.
Let’s consider two aspects of single source publishing, or single sourcing as it’s also known:
- Developing documentation on a wiki and then publishing it in other formats.
- Using some other tool to develop the documents, then publishing them on the wiki.
No wiki is an island
The burning questions are these:
If I write my documents on the wiki, are they stuck there?
If I choose to develop my documentation in another format, such as DITA, Word or FrameMaker, can I publish it on the wiki and get all that collaborative and social goodness happening?
Is a wiki like a remote island: Beautiful to behold, fun to live on, but nigh impossible to get to and from?
Why would we use a wiki in combination with another tool?
However, some customers may not be able to read the online documentation, perhaps because their work environment offers no Internet access or because they are constantly on the move. They need a downloadable version of the documentation that they can access behind the firewall. They may even want a printed manual. People may want to integrate our documents into their own environment, such as a developer’s IDE. Perhaps our translators require an XML version of the documentation to feed into their translation tools. We need to get content out of the wiki into a standard, portable format.
On the other hand, we may decide for various reasons to write our documents in a format like DITA XML, FrameMaker or Microsoft Word. Yet the collaborative and social aspects of a wiki are enticing. Like any good tropical islander we want to have our cocktail and drink it too. We need to get content into the wiki so that people can read it, share it and give us feedback.
What’s more, we need to do it again and again. In single source publishing, we need to develop the content on the wiki and export it regularly to other formats, or vice versa, preferably via an automated job.
Getting content into a Confluence wiki
Here are some great tools for importing content into Confluence.
Microsoft Word to Confluence
- Confluence’s built-in Office Connector can import a Word document and convert it to one or more wiki pages based on the criteria you define. The Office Connector processes one Word document at a time. Select ‘Import Word Document’ from the “Tools” menu. See the documentation.
- WebWorks ePublisher provides a sophisticated set of standalone tools for converting your Word documents to Confluence. You can design templates to define the styles and format of your output documents. Best of all, you can automate the conversion via batch processing and scheduling. This blog post shows the steps required to use ePublisher with Confluence, and has some good information in the comments.
FrameMaker to Confluence
- WebWorks ePublisher, mentioned above, also converts content from Adobe FrameMaker to Confluence. The image below shows the ePublisher style designer, a FrameMaker document and the content imported into a Confluence page.
DITA XML to Confluence
- WebWorks ePublisher is a star player here too, offering conversion and import from DITA XML to Confluence wiki.
- DITA2wiki is a stand-alone tool that converts DITA XML documents to Confluence format and uploads them into the wiki via a set of Ant commands. It’s an open source project on SourceForge. There’s some excellent discussion in the comments on this blog post.
Getting content out of a Confluence wiki
Confluence itself provides a good export to both PDF and HTML. Plugins provide the cherry on the top.
Confluence to PDF
- Using the built-in Confluence PDF export, you can export a single page, a selection of pages or an entire space into a single PDF file. You can also customise the PDF layout and stylesheets.
- Scroll Wiki Exporter, a Confluence plugin, provides flexible themes for configuring PDF layout and styles. You can select one of Scroll’s built-in themes and configure your table of contents, header and title pages. For even more flexibility, you can add your own theme plugins. Scroll supports themes based on DocBook XSL stylesheets. See the Scroll developer’s guide.
Confluence to Microsoft Word
- Confluence can export a page to Word. (Select ‘Export to Word’ from the ‘Tools’ menu.) This option performs a basic conversion of wiki content to HTML and applies some Word CSS stylesheets. It processes just one page at a time.
- Scroll Office is a Confluence plugin. Once installed, Scroll Office replaces Confluence’s built-in ‘Export to Word’ functionality. You can define your templates in Word in the usual way, and upload them to Confluence as global templates or space templates. When you export your Confluence pages to Word, Scroll Office will use those templates to build Word documents from the wiki pages. You can export a single page or a hierarchy of pages. Scroll Office provides additional features such as enforcing page-breaks, setting the page orientation to landscape or portrait, and ignoring content. The latest version offers a REST-style API for automated export. This blog post gives a good overview of the Scroll Office features.
Confluence to HTML
- Using the built-in Confluence HTML export, you can export a single page, a selection of pages or an entire space to HTML. Confluence supplies the HTML and associated files in a zip file.
Confluence to XML
- Confluence itself provides an XML export. The XML produced is a proprietary format and is intended for backups or for transferring a space from one Confluence instance to another. If you write your documentation on Confluence and your customers have Confluence too, then you can export your manuals to XML and customers can upload them onto their own Confluence site. This is probably not an oft-occurring use case, so from a technical writer’s point of view the XML export is not very exciting. ツ We at Atlassian do provide downloadable forms of our documentation – more in the section below.
- Scroll Wiki Exporter converts Confluence pages to DocBook XML, which is exciting to a technical writer. When offered an XML export we see worlds of possibility opening up, with portability to various document formats. OK, agreed: You do have to wonder sometimes about the things that excite us.
Confluence to Eclipse Help
- Scroll Wiki Exporter, mentioned above, is the tool you need. How cool, to write your documentation and online help content in Confluence wiki and convert it to Eclipse Help format! What I didn’t realise until recently, is that you can use a cut-down version of the Eclipse Help platform to provide online documentation for any system. It doesn’t have to be an Eclipse tool that you’re documenting. For some ideas, take a look at a couple of articles about documenting your project using the Eclipse help system and converting Confluence pages to Eclipse Help.
Confluence to JavaHelp
Does Atlassian provide PDF, HTML and XML versions of our own documentation?
Yes. We use the out-of-the-box Confluence export functionality to provide PDF, HTML and XML versions of our documentation. People can download the files from our documentation wiki. For example, here are the Jira documentation downloads and the Confluence documentation downloads.
For those people who would like to use our XML files to recreate the documentation on their own Confluence sites, we provide instructions on setting up your own local documentation.
If you know of an import/export tool that I haven’t mentioned, or even better if you’re thinking of developing one, let me know. For example, how cool would it be if we could convert to DITA as well as from it! I’m interested to hear what other conversions you need, to get onto or off a wiki island. For example, what formats would be useful to aid in translating wiki-based documentation to different (human) languages?
Another cool idea would be for the well-known HATS, such as RoboHelp, MadCap Flare and Author-it, to offer export to Confluence wiki as one of their output formats. I’ve heard about a project that successfully converted RoboHelp documents to Confluence, but I think it was a once-off conversion. Does anyone have any stories to tell here?
That’s it, for now
I think that portability and interoperability are the Next Big Thing for wikis. As a technical writer, I have a vested interest in this area. I’m pretty passionate about it too.
In the meantime, sit back and sip your Blue Hawaii with the cherry on the top, comfortable in the knowledge that you will not be marooned on your wiki.