I got dragons and tweets in my documents

You may think you have problems, with the odd misplaced apostrophe or errant semi-colon in your documents. Well, there are dragons prowling around mine, and tweeting dragon slayers too!

A few weeks ago some smart Atlassians had the idea of making it feel like fun to set up a number of our applications as an integrated Atlassian suite. (I work at Atlassian, makers of Confluence wiki, JIRA bug tracker, and other applications for software developers.)

We’ve known for a while that it’s, uh, difficult to integrate our apps. In fact, people have used somewhat stronger words to describe the process. The problem is that the applications were developed separately, and not originally intended to talk to each other. But now we’re working towards providing an integrated platform. So, a group of Atlassians mused, why don’t we turn the setup task into a challenge and offer our doughty customers and other brave souls a reward when they get to the end?

And so the “Here Be Dragons” project was born. At heart it’s a set of documents that leads people, or “dragon slayers”, through the process of integrating six Atlassian applications. It’s also a quest, where the hero acquires better armour and more strength as he passes each of the eight stages. And behind the scenes it’s serious stuff, because it’s given us a good idea of exactly what we need to improve to make the integration process painless.

The documentation

We needed a stalwart set of documents to lead people through a typical installation and integration process, with detailed step-by-step instructions and even exact values to put into each configuration field. The idea is that people can set up their suite and get it working on the basic configuration, and tailor it later to their specific needs. I was the lucky technical writer given the job of writing the documents. It’s been a lot of fun, a lot of hard work, and one of the most unusual documentation jobs I’ve ever done.

It was a collaborative effort, with me writing the documents, testing each step in Windows as I went along and making deductions about the UNIX steps. Other people moved in to test the UNIX side of things. Jason from our Design team did the awesome art work for the documents and the T-shirt. Yes, of course there’s a T-shirt! Other technical writers, QA people and product managers contributed their knowledge of specific applications. Now Charlie the Dragon Slayer lives and breathes. (“Charlie” is the affectionate name given to the dude in the Atlassian logo. He also plays a major part in the Dragons documents.)

Twitter integration in the documents

I also added Twitter to the mix. Each page of the “Here Be Dragons” document offers our dragon slayers the chance to tweet their status, and pre-populates the tweets with suggested words. It was great fun composing the tweets and it’s even more fun now, watching the tweets pop up in the Twitter stream.

On Thursday morning a few brave souls and true had already started out on their dragon quest:

I got dragons and tweets in my documents

Pre-populating Twitter tweets

You can set up a hyperlink for people to click, that will open Twitter in their web browser and put some words into their Twitter message. If they haven’t yet logged in, Twitter will prompt them to log in. They can choose to edit the words, or just leave them as they are. They then send the tweet by clicking the Twitter “Update” button as usual.

All you need to do is add an HTML link pointing to the person’s Twitter “home” page and specifying a “status” parameter in the URL. Something like this:

<a href=”http://twitter.com/home?status=Hallo World”>Say hallo to the twittersphere</a>.

Here it is as a link:

Say hallo to the twittersphere.

If your message includes funny characters like a # sign, then you will need to URL-encode the message. For example, if you wanted to pre-populate a tweet with “Hallo World #testing” you would use this:

<a href=”http%3A%2F%2Ftwitter.com%2Fhome%3Fstatus%3DHallo+World+%23testing”>Say hallo to the twittersphere</a>.

Here’s a web site that will URL-encode your text for you.

Is “Here Be Dragons” really technical documentation?

Yes it is. The quest, tweets and pretty pictures happen around the edges. The central part of each document is hard-core technical how-to.

Scott Nesbitt has written an interesting post on the DMN blog about making user documentation more usable and user friendly. A dragon quest is a bit extreme, and it’s not something you get the opportunity to do often. But I agree with Scott that there’s a place for a lighter touch in much of the online documentation we write. It’s a delicate balance. On the one hand, it’s important that the writing style does not annoy or offend the reader and does not detract from the content. We also need to be aware of people whose first language is not the one we’re writing in. On the other hand, the occasional touch of humour or personality can focus the reader’s attention onto the page.

Dragons was a fun project. My other technical documentation assignments will seem a bit tame for a while.

The URLEncode and URLDecode Page

Yard table assemblage instructions

These “Yard table assemblage instructions” were included with a garden table we bought. Actually, the structure of the guide is good. There’s a list of parts and then the “how to”. It’s just the language that needs a bit of tender loving care. I love the way it degenerates towards the end, as if the poor author just gave up because it was too hard.

Assemblage parts:

1.One piece of iron flower pattern glass (in midst have a hole).

2.Four table feet.

3.Two fixed stators.

4.Eight screws.

5.Eight screw caps.

Assemblage method:

1.Use the screws and screw caps screw down the table feet and fixed stators.

2.Table top is upward.

3.half-round plastics of under the table top direct against the table feet, Then press it down.

We did manage to assemble the table with no trouble.

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.