Chocolate, dragons, technical writers and team spirit

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):

Chocolate, dragons and technical writers

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:

Chocolate, dragons and technical writers

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?

Article about Confluence wiki for technical documentation

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

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

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!

Google Wave in Confluence wiki pages

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!

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