Blog Archives

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

Twitter as a medium for release notes

In the last couple of weeks, I’ve been trying an experiment — using Twitter as a medium for release notes. It’s been interesting, so I thought you’d like to read about it. We could use Twitter in other ways related to technical documentation too, such as hints and tips or FAQs. Let me know if you’ve done that already!

I’m going to start with a short introduction to Twitter, mentioning particularly the aspects that I found useful when tweeting release notes. If you’re already a twitterologist, you may want to skip that bit. Then I’ll describe how we’ve used Twitter as a method of communicating the highlights of our release notes.

An introduction to Twitter

Twitter is a service that allows you to send short messages to anyone who is interested in reading them. You can sign up for a free account at http://twitter.com. Then just type in your message where Twitter asks somewhat abruptly “What are you doing?” and click “Update”. Bob’s your uncle, you’ve tweeted.

Tweets

“Short” messages? Oh yes, very short, especially in technical writing terms 😉 The maximum length of each message, or tweet as they’re called, is 140 characters. There’s an art to saying something meaningful in such a short message. Especially when the message is a release note highlight. So be warned, you may spend quite a bit of time tailoring your tweet.

The tweet below illustrates a number of conventions tweeters use to make as much as possible of those 140 characters. I’ll tell you more about the conventions later, and how we can use some of them in our tweeted release notes.

Twitter as medium for release notes

Twitter as medium for release notes

Followers

According to some reports, there are approximately 10 million people using Twitter, and its growth rate is around 1,382 (more than a thousand) percent per year. (See Web Strategy blog.) That’s an awful lot of tweets to read. So what you do is “follow” people. Twitter will send you the tweets of the people that you are following. Similarly, other people will follow you so that they can read your tweets.

You can restrict the visibility of your tweets to only people you’ve allowed to see them. You can also block specific people from following you.

RT (retweet)

What I’ve found extremely interesting in Twitter is the conventions that have sprung up as people start using it for wider and more specific purposes. “Retweeting” is one of those conventions. If you like what someone said and want to spread the word while attributing the goodness to the original tweeter, you can “retweet” their message. Simply add the letters “RT” into your message, copy the original text, and tweet away. What’s more, there are Twitter clients that do this for you automatically. I’ve mentioned some clients later in this blog post.

In the tweet illustrated above, Alister Scott has retweeted one of my tweets. Thank you Alister 🙂

@ replies

When you want to reply to someone, or refer to them in such a way that they’ll know you’re doing it, include an “@” and the person’s Twitter username. For example, “@sarahmaddox”. Many clients provide a “reply” option that does this for you. Clients also have a separate column or tab showing the @ replies directed to you, so that they don’t get lost in the main stream of tweets.

#-tags and search

Another very useful convention is the #-tag. Let’s say you are sending a message about a particular subject, and you think other people would like to read and to send tweets about that subject on an ongoing basis. This may be for fun or for a more serious purpose. Just think up a keyword, prefix it with a “#”, and include it in your message.

In the tweet illustrated above, I used “#googlewave”.

Here are the realtime results for a Twitter search on “googlewave”. And here’s what people are saying right now about “funnywords”.

Other people will start using your keyword, and they will also search Twitter for other messages that contain the same keyword. Many Twitter clients will do the search for you. Twitter search returns results from all tweets sent by anyone in the whole wide world, not just the tweets sent by people you are following.

Combined with the #-tag, this makes a very interesting combination for our tweeted release notes.

Short URLs

A URL can be very long, consuming far too many of those valuable 140 characters. Luckily there are a few services on the web that will shorten your URL for you. The service gives you a short string that you can include in your tweet (or in an email, or a blog post, etc). When other people click the short string, they are bounced back to the service’s URL and then forwarded on to your original URL. Examples of such a service are TinyURL.com, bit.ly and tr.im.

In the tweet illustrated above, I used TinyURL.com.

Twitter clients

One of the most magical aspects of Twitter is that you don’t have to go to Twitter.com to use it. There are a number of Twitter clients that add useful functionality to your desktop and make it possible to tweet from your phone too.

The clients have built in extra functionality as the Twitter culture evolves:

  • The use of a #-tag triggers an auto-link. If you click the link, it launches a Twitter search.
  • The use of “@username”, e.g. “@sarahmaddox”, links to the user’s Twitter profile e.g. mine.
  • Clients like TweetDeck provide sophisticated search functionality. You can define search criteria using AND, OR, quotes, etc and build a “permanent” search that notifies you whenever a new tweet arrives matching your criteria. The matching tweets can be from anyone, so they’re not restricted to your friends.
  • Clients supply an easy way of shortening URLs. Some clients do it automatically, via a specific URL-shortening service like TinyURL.com, bit.ly or tr.im. Other clients offer you a range of services to choose from.

I have TweetDeck running on my Windows XP desktop and on my Windows Vista laptop. It’s built on Adobe Air and has a lot of useful features including a sophisticated search capability. Here’s what it looks like. In the left-hand column are some tweets from people I’m following. Next are replies sent to me (via “@sarahmaddox”). The two right-hand columns are specific searches I have set up. All this is configurable, including the order of the columns:

Twitter as medium for release notes

Twitter as medium for release notes

TweetDeck gives a handy notification when new tweets arrive from people you are following, or as replies to you, or that match your search criteria:

Twitter as a medium for release notes

Twitter as a medium for release notes

Want to read and send tweets from your phone? Well, you can. On my iPhone, I have both Twitterific and TwitterFon. I prefer TwitterFon — see screenshot further down this blog post.

You can also send tweets to Twitter via SMS. That’s what I did before I got the iPhone. So at least you can tell people what you’re having for dinner, even if you can’t read what they’re having until you get back to your computer 😉

Tweeting our release notes

So, how can we make use of all the above features and conventions to use Twitter as a medium for our release notes?

Aim

To emit a tweet per major highlighted point in the release notes, to include a link to the release notes and to provide a way for tweet consumers to see a collection of such related tweets.

A consideration

In general, people read only the last few minutes’ worth of tweets. It’s not like email, where people make an effort to at least scan their inbox when they’ve been out of touch for a few hours or days. We need to make sure our design catches as many people as possible, and shows them where to go for more information if they want it.

What we did

Here’s the plan of action:

  • Use Atlassian’s corporate Twitter account, rather than a personal account. Release notes are in a weird place, partly technical documentation and partly marketing information. People follow Atlassian’s Twitter ID and know what to expect from it i.e. company news. So they’re not dismayed to receive marketing-type information.
  • Use a #-tag to tie the tweets together. This is the most exciting bit. It provides a way for tweet consumers at any time to see a collection of such related tweets. A collection of release highlights is… the release notes. Ta da ♪ ♫
  • Use a shortened URL (e.g. TinyURL.com, bit.ly or tr.im) to link to the release notes themselves, so that people can read the full details if they want to.
  • Don’t send out all the tweets at once. This would spam people, and a number of other people would miss out on your news because they’re not reading their tweets at the time. Instead, send out two tweets a day, the second about four hours after the first, for two or three days.
  • Try it out for three or four product releases, then assess feedback and decide whether to continue.

The results

So far, I’ve tweeted about two of our product releases: the Atlassian Eclipse Connector 1.0 and Confluence 3.0.

For the Eclipse Connector 1.0, I used a tag of “#EclipseConnector10”. (#-tags are not case sensitive, because the Twitter search is case agnostic.) Here’s a screenshot of the resulting search on the Twitter.com web UI, at a particular point in time:

Twitter as a medium for release notes

Twitter as a medium for release notes

In the above screenshot, you can see the format we’re using for each tweet: the text of a highlight from the release notes, plus the #-tag (“#EclipseConnector10”) plus the short URL (“http://bit.ly/4mTLf&#8221;). Here’s the full content of one of the tweets:

Manage your Crucible code reviews via Eclipse Mylyn’s task-focused interface #EclipseConnector10 http://bit.ly/4mTLf

Of course, the search may or may not show something quite different if you click it now.

What’s interesting is that I tweeted using the Atlassian account (the tweets with the dark blue icon of a dude holding up  slice of the globe) and other people retweeted or just repeated the tweets. ‘Coz they liked them. Those are the entries with “RT” in the above screenshot.

For the Confluence 3.0 tweets, I used the tag “#Confluence30”. Here’s a screenshot of the resulting search on the Twitter.com web UI, at a particular point in time:

Twitter as a medium for release notes

Twitter as a medium for release notes

And here’s a screenshot showing the resulting search via TwitterFon on the iPhone:

Twitter as a medium for release notes

Twitter as a medium for release notes

And you can check what the search yields now.

Nothing can go wrong go wrong go wrong

Heh heh. Take a close look at the two screenshots above. One person “hijacked” our #Confluence30 tag to communicate a problem he had when upgrading to the new version of Confluence, and the workaround for the problem

Of course, it was totally foreseeable that people would tweet problems as well as praise, and would include “our” #-tag in their tweets. Nothing is sacred on Twitter. We decided it would be interesting to go ahead and see the sort of response we get. After all, people are saying all sorts of things about us all the time, on and off Twitter.

The iPhone screenshot above shows the same person’s problem tweet, plus another person who was letting people know about a particular feature in the Confluence release (Twitter-like status updates).

It’s been a fun and interesting experiment.

Other uses of Twitter

People are getting very creative with Twitter. Wikipedia lists some of the unusual situations where Twitter has proved useful.

As technical writers we can probably think up a gazillion ways to use Twitter. We could tweet hints and tips, or even FAQs if we’re super wordsmiths, using the #-tags and shortened URLs much as I’ve shown above. Have you tried this or anything similar?

%d bloggers like this: