Posted by Sarah Maddox
Warning: Not for sensitive viewers. This post contains a truly awful pun, bad grammar and lamentable verse. Read on at your own peril. Are you sitting down?
At work we write the release notes a while before each release and let our colleagues know when page is available for their edification and their delight. We let them know via a blog post on our internal wiki. Such blog posts tend to be a bit monotonous. “The Crowd 2.0.3 release notes are now available. Please note that this document is a draft and is for internal information only.”
This week I had a bit of fun. It was a spur of the moment thing that took me just two minutes. Hence the deplorable verse:
Rhyming the Crowd 2.0.3 Release Notes
Now you can see
What’s in Crowd 2.0.3
We’re not kiddin’
But the doc’s still hidden
So don’t give it away
But do have your say
Tom, one of our developers, snapped back with this comment:
“Doggerel fooding the release notes?”
LOL. Nerd humour at its best. Thanks Tom!
To “dogfood” is to use your own product, so that you experience its strengths and weaknesses intimately. The term started off as a noun phrase in “eating your own dog food” but is now commonly used as a verb too. In certain circles. 😉
Posted by Sarah Maddox
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.
“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.
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.
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 🙂
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”.
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.
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.
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:
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:
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?
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.
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.
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:
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”). 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:
And here’s a screenshot showing the resulting search via TwitterFon on the iPhone:
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?