A few days ago, our technical writing team went on a chocolate outing. This is not a rare occurrence. This time I have some pictures and a few musings about the confluence of teams and chocolate.

Concept:

Reference:

Task:

We decided that was one user guide we could all follow without difficulty!

chocolate.inspire(team)

For me, one of the most important aspects of my job is the team I work with. After all, I spend most of my waking life with them. It’s good to build up some common interests, other than the work itself, so that you have something to talk about, something to bind you together, even something to complain about.

I think fun is very important. But “fun” is a fuzzy concept. People have different ideas of what constitutes fun and technical writing teams typically consist of very disparate individuals. So how on earth do you find something that everyone will consider fun, interesting and invigorating?

Funnily enough (heh), we’ve found that it just happens. We have a great bunch of people in our team. Every one of us wants everyone else to feel good in the team. So when a possible “common interest” arises, everyone buys into it.

skate.go()

Earlier I wrote that it’s even good to have something to complain about together. Don’t we all love to exclaim in anguished tones, and isn’t it a good thing if the object of such gleeful anguish is not our job! I have a Calvin and Hobbes cartoon above my desk at work, showing Calvin’s father with a mangled bicycle, obviously the result of a bad stack. The caption reads something like:

“The secret to enjoying your job is to have a hobby that is even worse.”

Our technical writing team is keen on rollerblading. Actually, we’ve only done it once, but we plan to get out there again soon. And being keen doesn’t mean we do it well, just that we’re happy to give it a go. Or simply to watch our team mates fall off the blades! We made it into the Cherryleaf I’m a technical writer and I’m not boring annals.

But can you guess what the most popular common interest is? You got it: chocolate. And it’s not something we complain about!

chocolate.reward(jens)

We’ve taken to “rewarding” other people, those who are not fortunate enough to be technical writers, when they do something that improves the documentation. How do we reward them? With chocolate of course.

Our latest reward went to Jens, who is doing some awesome work on a “documentation” theme for Confluence wiki. (Yes, it’s true! I’ll let you know more about it when there’s a prototype ready for trial.)

We went to at Max Brenner in George Street, Sydney. Clockwise from the left, here are Rosie, Jens, Ed, Giles and Andrew (I was taking the photo):

Lucky Jens!

tShirt.glow()

Another thing we do to engender team spirit is to dress alike.

Heh, just kidding. But on this occasion, we all made sure that we wore our new Atlassian Dragon Quest T-shirts.

Warning! The shirts are very green. When we all appeared together, an involuntary gasp of horror escaped Penny, one of our QA engineers:

“My eyes, my eyes.”

So here we are, the Atlassian technical writers on a chocolate outing in our Dragon Quest T-shirts. Clockwise from the left — Ed, Giles, Andrew, Rosie and Sarah:

I count myself extremely lucky to be part of such a great team! Do you have any stories about what your team gets up to?

My article on “Using a wiki for technical documentation” appears in the October edition of Southern Communicator, the Australian and New Zealand journal of technical communication. Exciting!

A big thank you to Janet Taylor and the journal’s editorial team, both for inviting me to contribute and for allowing me to publish a PDF extract of the journal on this blog. Another big thank you to Marian Newell, who kindly gave permission for me to include her article here too. You guys are stars!

Click this link to download the PDF file containing the journal extract. Below is a summary of the content.

Using a wiki for technical documentation

My article is on pages 6-10 of the PDF file. (Printed page numbers are 4-8.) It covers the following topics:

• Overview — what a wiki is and does.
• Workflow — draft, review, publish.
• Tracking — page history, notification of updates, reverting to a previous version.
• Permissions.
• Adding structure to your documentation — table of contents, left-hand navigation bar, logical page ordering, content re-use.
• Release management.
• Agile development methodology.

(The article is based on my earlier presentation of the same name. You may find the slides and screenshots a useful adjunct to the printed article, since the images are rather small in the article.)

Trends in British technical communication

The journal’s editorial team allowed me choose another article from the journal to include in the PDF extract. I chose Marian Newell’s very interesting article, “Trends in British Technical Communication”. She discusses a number of topics, including:

• Our job titles — Are we technical writers, technical communicators, technical authors, content creators…? Personally, I prefer to be known as a technical writer. But read what Marian has to say.
• Deliverables and workplaces — printed or online content, large long-lasting projects or smaller shorter projects.
• Tools and methods.
• Generalisation and specialisation.
• Translation.
• Fads and fashions — user-generated content, social networks, information facilitators, modular content.
• Quality and productivity — Is “good enough” good enough? Should we obtain a standard qualification to put us on a par with other professions?
• Economic and commercial factors — global economic crisis, current demand, freelances and agencies, outsourcing, offshoring, remuneration, standards of written English.

And more

The PDF file also includes:

• The editor’s introduction by Sue Woolley.
• A foreword by Geoffrey Marnell about the recent ASTC and PLAIN conference, a joint event in Sydney organised by the ASTC and the Plain English movement

A beta version of the next Confluence release is out. And guess what — it’s got gadgets. This is pretty cool, so I’m jumping the gun and telling you about it right now.

It’s still just a beta release: Confluence 3.1 Open Beta. The announcement is on the Atlassian News Blog, along with an invitation to try it out. So I got myself a copy and put some gadgets onto a wiki page.

Now, the gadgets I chose are perhaps not the most useful. The most usual business case would be to add gadgets published by other Atlassian applications. For example, you might want to add a gadget that displays some information from another Confluence site or from  JIRA, Bamboo, FishEye or Crucible. (Those are other applications developed by Atlassian, the company I work for.)

But for me, the fun bit is that I can add the gadget that I created and blogged about 8 months ago.

The same 2 gadgets in 3 different applications

Here’s a screenshot of a Confluence wiki page with two gadgets. One is mine, displaying an up-to-date list of recent blog posts about technical writing from WordPress.com. The other gadget was created by Donna, our support diva, showing recent entries in a Jive discussion forum. (Click the image to enlarge it.)

Gadgets on Confluence wiki pages - oh, and in JIRA and iGoogle

Here are the same two gadgets on my iGoogle page:

Gadgets on Confluence wiki pages - oh, and in JIRA and iGoogle

And here they are in JIRA:

Gadgets on Confluence wiki pages - oh, and in JIRA and iGoogle

How do you add a gadget to a Confluence page?

Your Confluence page can display two types of gadgets:

• Internal — These are gadgets published by the same Confluence site as where they are displayed. Typically such a gadget would display information sourced from the Confluence site, such as an activity stream or a search function.
• External — These are gadgets published by another Confluence site, or a JIRA site, or even something totally different like Remember the Milk, a hamster in a wheel or a pet monkey.

If your gadget is external, the Confluence administrator needs to add the gadget to the list of available gadgets before you can add it to your Confluence page. This needs to happen only once for each gadget.

To make an external gadget available in your Confluence site:

1. Log in as a Confluence administrator.
2. Go to ‘Confluence Admin‘ and click ‘External Gadgets‘ in the left-hand navigation panel.
3. Paste the URL of your gadget into the field labelled ‘Gadget Specification URL‘. The URL should point to the XML file that describes the gadget.

For example, take a look at the URLs for the two gadgets in my screenshots above. The URL for the WordPress gadget is:

http://hosting.gmodules.com/ig/gadgets/file/117695765658379330528/
WordPress-dot-comRSSFeed.xml

And the URL for the Jive forums gadget is:

http://confluence.atlassian.com/download/attachments/203394872/forums.xml

Friendly warning: I’m just using my gadget as an example here. It’s a total hack, so please don’t insert it into any Confluence sites that matter! You’ll get all sorts of weird display problems, plus potential security issues too.

To add a gadget (external or internal) to a Confluence page:

1. Create a new page or edit an existing page.
2. Put your cursor in the edit box where you want the gadget displayed.
3. Click the ‘Insert/Edit Macro‘ icon  in the toolbar.
4. You’ll see the ‘Select Macro’ popup window. Enter some text into the search box at top right, to find the gadget you want.
   
5. Click the gadget you want. You’ll see a preview of the gadget. Most gadgets also offer you some options to configure the gadget, such as width of the display, background colour, etc.
   
6. Change the settings if you like, then click ‘Insert‘.
7. Save the Confluence page.

Extra authorisation step (OAuth)

Some gadgets require extra authorisation, to reassure the publishing server that it’s OK to send its data to the server where the gadget is displayed. Gadgets use an authorisation protocol called OAuth. There are two parts to the authorisation, one performed by the administrator and one by the person adding the gadget to or viewing the gadget on the page.

1. The administrator needs to set up the OAuth relationship between the gadget publishing server (called the provider) and the displaying server (called the consumer). This authorisation step needs to happen only once for each site. Once you’ve authorised one server to send information to another server, then you can add multiple gadgets from that server. For example, let’s say you want to display JIRA gadgets on a Confluence page. Your JIRA server needs to trust your Confluence server. So you’ll need to add Confluence as an OAuth consumer in JIRA. To do this, you will give JIRA the URL of your Confluence server. The instructions are in the JIRA documentation.
2. When you add a gadget to a page, you will need to authorise the display of information under the authority of your user ID. Similarly, every user who views the page will need to authorise the display of the information under their user ID.  The authorisation lasts for a while (a week or so, unless you revoke it). The gadget will display a ‘Log In and Approve‘ button. When you click the button, you will go to the login page of the site concerned. Log in and then approve the gadget’s access to the server’s information. Now you’ll see the gadget information displayed. There’s a full write-up in the Gadgets documentation.

Phew, I’m glad we’ve got that out of the way!

Would you like to try it yourself?

The Confluence 3.1 beta release is out, so you can hack away. If you’re very brave, you could even write your own gadget and put it on a Confluence page!

I’ve just come across a new plugin developed by 224 team. It provides a Confluence macro that lets you embed a Google Wave into a Confluence wiki page. I’ve just got back from holiday, so I haven’t played around with the plugin much yet. But I’m blogging about it so that more people can try it out too. It’s cool to see this sort of development happening and even to get involved in the early stages.

A friendly warning: The plugin is pretty new, so it’s best to try it out on a test installation of Confluence.

To install the plugin:

1. Download the JAR file from the link provided on the 224 team page (at time of writing, the link is here) and save it somewhere on your computer.
2. Open Confluence in your browser and go to “Confluence Admin”.
3. Click “Plugins” in the left-hand menu.
4. Click “Browse” and find the JAR file that you saved in step 1. Select the file.
5. Click “Upload”. You should now see the “wave” plugin listed on the page, in the middle and slightly to the right of the words “Installed Plugins”.

To embed a wave onto a wiki page:

1. Create a new page or edit an existing page.
2. Add the {wave} macro, including the URL of the wave you want to embed. You can add the macro by typing the wiki markup or by using the Confluence macro browser. The format is:
   {wave:url=my.wave.url}

I decided to add my wave within a {panel} macro, to make it look a little neater. Here’s the code I used (but it’s a private wave, so you’ll need a different wave URL):

{panel}
{wave:url=https://wave.google.com/wave/#restored:wave:googlewave.com!w%252BFelxosoIC.2}
{panel}

Once I’d added the wave to my Confluence page, I replied to one of the segments in the wave on the Confluence page. See the segment that starts with “I’m replying via the Confluence plugin”:

Google Wave on Confluence wiki pages

Then I had a look at the same wave in the original Google Wave client. Ta da! My reply appears there too:

Google Wave in Confluence wiki pages

So you can take part in a wave from within Confluence. Awesome. Once I’ve found a chocolate plugin, why would I ever need to leave Confluence?

The developers of the Confluence Wave plugin say that they have great plans for the plugin. They’re inviting discussion on the Confluence feature request and on the 224 wave page. If you have a Google Wave account, you can even join the 224 team wave. Fun!

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.

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.

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

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.

As wikis mature, we’re using them for more complex business cases such as technical documentation, business analysis and project management. It’s becoming more and more interesting, if not essential, for wikis to support the import and export of content to and from other formats. Most wikis allow you to convert their pages at least to PDF and HTML. But what of other formats, and what about tools for getting content into wikis as well as out of them?

For the past couple of months I’ve been writing myself notes whenever I see mention of such a tool. Now I’ve added a bit of web searching to the mix. Here’s the resulting motley collection of tools that convert to/from wikis to/from wherever/whatever. It’s by no means complete, its order is decidedly random, and it focuses on Confluence and MediaWiki more than on other wikis, because Confluence is the wiki I use and MediaWiki is a biggie. If you know of other tools not mentioned here, I’d love it if you add a comment to this post.

What’s not in this post

I haven’t included the various widgets, gadgets and macros that allow you to include content onto a wiki page dynamically from another source, so that the external content is displayed to the user when the wiki page is rendered. Examples of these not-included tools are dynamically-rendered RSS feeds, Twitter feeds, extracts of code from source repositories, etc.

Rather, I’m looking at tools that convert an entire document or set of documents from one output format to another.

Converting from a wiki to something

Converting from something to a wiki

Wow, so many?

Yes, and more. My list is just a start! From the number of tools already being used and under development, it’s clear that this is one of the growth areas for wikis in the next year or so. Some of the tools above are already a core part of one or more wikis. Others are stand-alone, fully-featured and well supported publishing or authoring platforms. And still others are plugins, extensions or add-ons created by the “ecosystem” of talented developers that surround and support wikis.

At this time, it’s a case of caveat explorator, for anyone needing to convert their documents to or from a wiki. Especially if you need to convert your content regularly as part of your authoring and publishing workflow, it’s worthwhile doing some in-depth investigation before using some of the tools mentioned above. Even more so if you’re looking for a “round-trip” conversion, where you need to convert from one format to another and then back again without losing content or formatting.

On the other hand, many of the above tools are already much used and well supported. It’s an exciting area for anyone interested in or already using wikis. Please let me know about all the tools I’ve missed.

“Guided help” – that’s when you actually do the task you need to do, and some helpful bubbles or other UI prompts tell you what to do next. You’re not reading documentation, reading help or watching a video. You’re not working on a sandbox or a test site. You are actually getting the job done and learning at the same time.

I’ve recently tried SHO Guide, a tool for creating guided help scripts. It was a lot of fun and a very worthwhile experiment.

In a nutshell, this is what happens: Using SHO Guide, you write scripts and publish them. This produces a “.sho” file for each script. Your customers then use SHO Player (freely downloadable) to play the script. It hooks into the UI of your application and guides them through the steps they need to take.

First impressions

SHO Player is a quick download (1.3 MB). Installation is painless (apart from the usual chattiness from my Windows Vista OS). SHO Guide is a longer download (60 MB).

When you get your SHO Guide licence key, username and password, you also gain access to the “Resources” part of the SHO web site. This has plenty of tutorials, FAQ, a support forum and information about training. The Quick Start tutorial is very good. Fast, with just the right amount of information to get you started. It guides you through creating a SHO script for Notepad.

Creating scripts with SHO Guide

You can record a series of steps, by clicking the “Record” button in SHO Guide and then performing the steps in the application you’re documenting. Then you can go back later to edit, insert or delete steps as required. This is very useful.

The SHO Guide authoring environment has a familiar look and feel to people who have used various types of authoring tools:

SHO for guided help

(Click the image to expand it.)

On the left of the above screenshot are the two scripts I’ve created, called “Create a space” and “View all blog posts”. Underneath the scripts are two more segments, hidden at the moment, where you can access extra step types and a library of images and other resources. In the middle is the bubble that the users will see, with various options for you to create conditional paths, filters and actions. It doesn’t take long before you know what’s what and where to find it.

The easiest way to start a script is to record it. Here’s a screenshot showing a recording in action:

SHO for guided help

In the above screenshot, I’m recording an activity on the Confluence dashboard, running in Internet Explorer. The red square shows the UI element that is currently in focus. At the bottom of the screen is the SHO Guide recorder panel, showing the key presses already recorded.  The icon of a video camera at far right means that the recording mode is active and ready for input. The icon changes to a hand when the recording is paused or busy.

Hint: It can take a while to save a recorded action. Wait until the hand changes back to a video camera before continuing with the next click or exiting from SHO Guide, otherwise your clicks may not be recorded.

The end result

Here’s a screenshot showing the starter bubble of a script I created for Confluence, helping people to create a wiki space:

SHO for guided help

The problem: You’re new to Confluence, or to another Atlassian application. You have to get something done, and you’ve no idea where to start. You’re panicking. You’re in a hurry. The UI is not helping, because it assumes at least a bit of knowledge. Atlassian, WTF??

The solution: Atlassian WTF!! The Atlassian Webapp Tutorial Fantastique.

Curious about the fairy in the bubble? She’s the Atlassian Webapp Tutorial Fairy, of course. She’s also a photograph of my earring. You can add images, videos and documents to your SHO scripts.

Here are a couple more screenshots of the same script in action:

SHO for guided help

So the user would click the “Create a space” link, as prompted by the green bubble. Confluence then opens the “Create Space” screen and SHO supplies the next bubble, prompting them to enter the space name.

SHO for guided help

In the screenshot below, see how you can present a choice of paths to the user. In this case, the “Do It For Me” option launches a set of automated steps — another cool feature of SHO.

SHO for guided help

The user also has the SHO Player toolbar, allowing them to pause or stop the script:

SHO for guided help

Want to see and read more?

Experimenting with and evaluating SHO was my Atlassian FedEx Day project. There are more screenshots in my FedEx 12 delivery note, as well as some notes about the requirements and limitations of the tool. What on earth is FedEx Day, you ask? It’s a period of 24 hours when Atlassians get to do something totally different from our normal day-to-day job, then present our findings to the rest of the company. It’s pretty cool. I wrote about it last week.

Wrapping it up

This was my first foray into guided help and into SHO. A big thank you to Matthew Ellison for mentioning SHO in his presentation on context-sensitive help at AODC 2009. (I wrote about it too.)

BTW, this was just an experiment. The scripts aren’t by any means production ready.

I haven’t had time to investigate SHO in detail. There are many possibilities, such as including sound, video and documents into your scripts, adding specific action types, trapping errors issued by the app, and so on. SHO Guide is easy to download and you can evaluate it for free for two weeks. The Transcensus guys, makers of SHO, have been very friendly and free with offers of help and discussion. Definitely worth a try. Fun too. That’s what it’s all about, huh.

I’ve just had the pleasure of reading Anne Gentle’s book, Conversation and Community, The Social Web for Documentation. I highly recommend it. The book is brim full of useful information and, even better, great ideas. This blog post is about some bits of the book that were especially interesting to me. When you read the book, you’re sure to find other sections that tickle your fancy or kick-start a killer idea

Conversation and Community by Anne Gentle

The book arrived in the middle of a busy week. My first impressions were: Yay, it found it’s way to Oz so quickly! Then I opened the package and saw the cover. You can almost taste the chocolate. Those people are all interacting with each other, great picture. What sort of keyboard is that — not QWERTY? Ah, the credits say it’s Danish. Cool.

It’s all about ‘now’

What really hits you when you read the book, is that the content is very current. It refers to blog posts written just a few weeks ago! You get the feeling that you’re engaging in a conversation with Anne and the other people she mentions, right now. You could go and comment on the blog posts and still be relevant. Awesome.

The foreword, by Andy Oram, sets the scene perfectly. Great opening: “A few years ago, this book could not have been written… A few years from now this book will be unnecessary… You are fortunate to have this book at this moment, for you can lead the next generation of information providers into the era of expert/amateur interaction.”

It’s all about ideas

Here’s a tip: When reading this book, have a notebook with you. The ideas will just keep popping into your head. For example, chapter 2 is a useful whiz-through of concepts and tools in the social web. Sprinkled throughout the chapter are some neat tips. It’s well worth a read, even if you already know most of the tools and concepts.

One idea I’d like to try, is using a Twitter feed right on the documentation pages as a way of displaying tips and FAQs. I haven’t quite figured out how to get the technology to do that for me. We need a Twitter widget for the wiki — one that shows a stream of tweets rather than just one tweet. But it’s almost possible. Then our community authors could tweet tips as they work!

Heh, this idea tickled my fancy: something to try when you’re struggling to write in a casual, simple style. Stick a picture of someone you know on your computer screen and pretend you’re explaining the concepts to them. (Page 23.)

Technical writers are in there, boots and all

Anne makes some excellent points about how our skills are transferable to the social web, particularly in integrating the social network into user assistance. (Page 25.) Key to the book is the point that readers of user assistance don’t usually care about where the information came from or who wrote it, provided it does the trick. (Page 9.) Our role includes taking this idea on board and working with the broader scope of available information.

That’s a bit daunting, but the book goes on to give guidelines on how to jump in, boots and all. Page 72 describes some participation models, and the following pages have pointers to getting involved in the social media.

How about style and standardisation? Those are endlessly debatable and particularly in the less formal online / social environment. Undaunted, Anne has written up some good guidelines. (Pages 184-8.)

Working with communities is an art unto itself

Anne encourages us to get started by listening, observing and then building up our own participation slowly, before establishing a community ourselves. Once we have a documentation community, there are ways to check the social weather in the community and keep it sunny. (Page 109.)

Anne notes that we can probably expect a small percentage of contributors, and that we should value them highly. She mentions the 90-9-1 rule: 90% reader, 9% infrequent contributor, and 1% active contributor. (Page 160.) This rings true with our own experience at Atlassian, of community contributions to the documentation. It’s interesting to see the researched statistics. And we do value our contributors, very highly. ♥

Here’s a clever metaphor cum reference to current wisdoms: “Teaching the community to fish (for information) feeds them longer than just answering questions without citing how you learned the information yourself.” (Page 137.)

Booksprints sound like so much fun, and so productive. I’d love to get involved in one. So it’s great to see some detailed advice from a book sprint diva.   The book has a long section (pages 112-124) going all the way from planning, through logistics to just plain fun.

So, did I like it?

Conversation and Community by Anne Gentle

Yes! The book is easy to read, authoritative yet friendly. That must be a hard balance to strike. Anne’s command of her subject, her wide-ranging interests and her skill with language make the book a pleasure to read. For example, I love the combined precision and pragmatism of this statement:

“This chapter contains a frozen-in-time list of some terms and tools in 2009 that are related to social media.” (Page 29.)

And the interesting perspectives on social contributions to Shakespeare’s scripts and the OED, gleaned by Anne from Alan Porter. (Page 66.)

Anne has tweeted that she’s experimenting with virtual book signings. Cool idea! I’m hoping her experiment succeeds and I’ll get a virtual signing of my copy too. Go Anne!

What other people are saying

I’ve purposefully restrained myself from reading anyone else’s review of Conversation and Community, so that I could write mine with an uninfluenced mind. Next I plan to read what everyone else has to say. A quick search reveals:

• The book’s overview page at publisher XML Press.
• Stewart Mader’s review at Future Changes.
• Jefro’s review at Jeff’s Open Source Resource.
• Various reviews at Amazon.com.
• Ellis’s review at Cherryleaf Technical Authors Blog.
• Sarah O’Keefe’s review at scriptorium Palimpsest.
• Rhonda Bracey at CyberText Newsletter.