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 in my documents

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

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 10 October 2009, in atlassian, technical writing and tagged , , , , , , . Bookmark the permalink. 17 Comments.

  1. This is such a radical idea and I love it. I also document products that can be a headache to integrate so an attempt to make it fun speaks a lot of sense. You’re lucky to work somewhere that allows these kinds of ideas to flourish.

  2. Thanks Haitham. Yes, I’m very lucky to have such a weird project come my way. We had a bit of debate about whether it was a good idea or not, and whether it would annoy people to see the dragon theme popping up in what is, after all, a necessary and demanding task. We made sure the technical how to instructions are at the centre of it all, and are not sullied by weird language. Then we just went ahead and had fun. 🙂

  3. Appan Ponnappan

    I also liked the idea of making it a ‘fun contest’. You can also look at the picture that I created for this products integration at:

  4. Great diagram! Thanks Appan. I’ve tweeted about it, and I’ve already had a comment “very cool” from one of the Atlassian product managers.
    Cheers, Sarah

  5. Sarah, this is just so outside the box, it needs its own adjective to describe it. I love it! Thanks for the inspiration. Forgive me, I cannot remember who posted a blog entry on whether tech writing is boring, but if THIS doesn’t dispel that myth, there is no hope.

    • Hallo Patty,

      Thank you for such glowing words! I wandered over to your blog and saw your post there too. It was great writing the Dragons docs. It demanded a lot of attention to detail, as well as thinking outside the box and just plain having fun. I also had the chance to work with our Design team, who created the images and colour scheme. Awesome! I love your phrase “true technical writing at its fire-breathing heart”.

      I see that “Write Trends” is a new blog. Good choice of name! I’ve subscribed to it now too.


  6. Sweet! Nice work, Sarah and team:) I was beginning to think that my musings in 2008 on the subject http://bit.ly/3JSzpG were too out-there…but your results prove otherwise!

    I’m really excited to see the notion of applying gaming frameworks to delivering user assistance take shape. I strongly believe that games provide the perfect example of how lines between user assistance and app functions are, more often than not, artificial and unnecessary. Looking forward to more updates, and new implementations!

    • Hallo Lisa
      That’s a really interesting blog post you’ve linked to. Thanks! I’d never heard of Gamelayers. Especially interesting is their game that turns web browsing into a treasure hunt. At the moment, their web site is down but I’ve had a look at their Twitter site and the articles about them via a Google search.

      Your blog post says “Let’s say, you’re a provider of software that is complex, spanning many subject matters and applications…” Heh, that’s just what the Dragons docs are about. Spooky. Our docs are slightly different, in that we haven’t built any game functionality into the pages themselves. They’re basically straight wiki docs with awesome images. I did discover how to add the pre-canned text for the tweets, so that the dragon slayers can just click a link to tweet their status. That’s turned out to be so much fun, watching the tweets come up.

      It’s great to have your comment, and awesome that you’re so keen on adding fun to tech docs!
      Cheers, Sarah

  7. Brett Hillebrand

    The dragons quest idea is brilliant, so out there is kinda stupid that no one ever thought of taking a task (thats quite frankly a pain in the arse to do – open company, no bullshit) and turning it into a step by step comical game – I really appreacite that humour.

    I think Atlassian will have set a trend with this, I forsee many other development teams (small and large, opensource and proprietry) catching onto this style of documentation.

    I myself will be reffering this to all developers at my small, opensource team. Much like Atlassians core values, theres *allot* of wisdom here.

    • Thank you Brett, I’m so glad you’re enjoying the docs. Let me know if your team does something similar or if you see other new quest-style docs appearing!
      Cheers, Sarah

      • Brett Hillebrand

        Hi Sarah, Just noticed something on Stage 2, Step 4 of the dragons quest.

        Upon completing the JIRA / Crowd configuration, when you go to restart JIRA you may already be logged in (because of crowds fantastic sso functionality) but you will not have Admin rights on JIRA. This is because crowd hasnt got the JIRA groups in it (and there is no step listed that I can see to add them). Hence, some of your slayers may get confussed. Perhaps it may be wise to add a step to import or create the groups in crowd?

  8. Brett Hillebrand

    Oh, also.

    Import the groups from jira to crowd before you restart jira otherwise when you login, JIRA will cache the crowd details without your group memberships and this will take some time to expire before it realises your now in the admin group

    • Hallo Brett

      Thanks for the feedback! The Dragons docs do actually instruct people to add all the necessary groups to Crowd. They do all the groups at once, in stage 1 step 5. You’re 100% right about JIRA caching the Crowd group authorisations. There’s not much we can do about that, because I’m not keen to instruct people at this early stage to go and turn off the caching. But I’ve added a note in a new step right at the end of the Dragons Quest, all about “Life after Dragons”. 😉

      I hope that will help people not to run into the same sort of issue. Do you think it would be useful if I add a note in stage 2 step 4, telling people to go back and do the group setup if they missed it in stage 1?


      • Brett Hillebrand

        Oh, how stupid of me ><. Having setup crowd before I skimmed that part.

        No, its probably unrequired, your right 🙂

        Thanks again,

  1. Pingback: Chocolate, dragons, technical writers and team spirit « ffeathers — a technical writer’s blog

  2. Pingback: Lombardi Development Blog » Blog Archive » Business intelligence, intelligent content and devices, games, and noise.

  3. Pingback: How to embed Twitter streams and prepopulate tweets in your document « ffeathers — a technical writer’s blog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: