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.
We decided that was one user guide we could all follow without difficulty!
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.
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!
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):
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?
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.
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:
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:
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. 😉