Blog Archives

Hints and tips via Twitter

Twitter is ubiquitous. People will read tweets because they’re short and punchy and because they go where we go. Rumour has it that, in contrast, people don’t read manuals. 🙂  We’ve been trying a few different ways of using Twitter’s sweetness in and around our documentation. Our latest experiment is called “Tips via Twitter”. I’m interested to see how it will work out.

We’re encouraging people to tweet hints and tips about our products. What’s more, we publish a live Twitter stream on a page in the documentation. This is what it looks like:

Hints and tips via Twitter

Hints and tips via Twitter

Kicking off the project

We’ve started with one of our products called Confluence wiki. On the screenshot above, the blue section labelled “ConfluenceTips” is actually a constantly-rolling stream of tweets. You can see it in action on the “Tips via Twitter” page in the Confluence documentation.

The idea is that people will enjoy sharing their hints and tips in an interactive Twitter stream, and will enjoy seeing their tips appear in the documentation. We’re trying the experiment for Confluence first – so we’re inviting people to tweet tips about the wiki. If it works out, then we’ll do it for another of our products, an issue tracker called JIRA.

Tweet tweet

If you like, you could tweet a hint about Confluence right now, and see it appear on the documentation page. Log in to Twitter, then click this Twitter link to get you started. Replace the words “My tip” with your hint. Be nice now! 😉

Embedding the Twitter stream

I’ve used the Confluence Widget Connector (that’s a wiki macro) to embed the stream of tweets into the page. The stream of tweets is the result of a Twitter search: http://search.twitter.com/search?q=ConfluenceTips

This is the wiki markup for the Widget Connector, as I’ve used it on the “Tips via Twitter” documentation page:

{widget:url=http://search.twitter.com/search?q=ConfluenceTips|width=500|height=1000}

Things that may go wrong

There are a few things that may go wonky with this experiment.

The most obvious is that maybe nobody will tweet. If that happens, the stream will dry up and we’ll have a big empty box on the documentation page. Luckily, we have a keen tweeter called @ConfluenceTips whose tweets show up in the search results too. Thank you @ConfluenceTips! I’ve also created a set of tweets that I used to seed the stream when I announced the experiment to the world. I’m hoping this will help to encourage other tweeters and give them an idea of what a tweeted tip may look like.

Another problem may be that people start tweeting weird or bothersome messages. I’ll be monitoring the stream. If necessary, I’ll remove it from the documentation page.

Anyone else tweeting hints and tips?

Let me know if you’re using Twitter for hints and tips, maybe publishing them in the documentation too, or doing something else totally cool.

Advertisements

Another Atlassian FedEx Day and a Confluence gadget on the way

A few months ago I wrote about my first Atlassian FedEx day ever. Now I’ve survived another. Plenty of dust, sweat and tears, and plenty of laughs, later, I have a brand new Confluence gadget to boast about. Well, actually I have 3 halves of a Confluence gadget and lots of lessons learned.

My aim for this FedEx Day was to learn more about developing gadgets. I’ve created a gadget before, but it was a generic Google gadget and not specifically an Atlassian gadget. Of course, if I can get a useful gadget working too, that would be awesome.

I’m part way there.

My JIRA Tips Gadget

Just so you know: It’s nowhere near ready yet.

The user story: People want to see JIRA hints and tips on their JIRA dashboard, rather than having to find their way to our documentation. We want the hints and tips to be housed on our documentation wiki, so that we can update them easily. People also want to see Confluence hints and tips on their Confluence dashboard, and Crucible hints, and so on.

The solution: Develop a “Tips” gadget for each product, starting with the JIRA Tips Gadget.

  • The gadget gets the tips, one at a time, from our documentation wiki, affectionately known as CAC.
  • On CAC, we have a set of tailored tips for JIRA, another set of tips for Confluence, etc. These tips can be part of the documentation too, provided they keep the required (minimalist) format. We’ll store them as children of a particular page, so that the gadget knows where to get them.
  • People can:
    • Add the JIRA Tips Gadget to their JIRA dashboard.
    • Add the Confluence Tips Gadget to their Confluence dashboard (by customising their Dashboard welcome message) or a wiki page.
    • Add any of the “Tips” gadgets to iGoogle, Gmail, etc.

Things I learned the hard way

FedEx tip 1: Don’t shut down your environment at the end of day 1. I made that mistake, and then spent two hours getting it back on Friday morning.

FedEx tip 2: Don’t install a Confluence plugin containing a gadget module that refers to a gadget spec residing on the same Confluence instance. I stored my gadget spec (XML file) as an attachment to a Confluence page. That seemed handy.  But the startup procedure found the gadget plugin and went looking for the gadget spec. It waited and waited and waited… 😉 Eventually I reinstalled Confluence and recreated all my configuration and data. Hence the two hours on Friday morning.

How far did I get?

The plan was to start with a very simple gadget and gradually make it more complex:

  1. First a URL-type gadget that does a straight grab of content from a page.
  2. Then an OpenSocial gadget (i.e. an HTML-type gadget), but still grabbing the HTML off the page.
  3. Lastly a full-blown OpenSocial gadget using the Confluence REST API.

1. The URL-type gadget

This is a quick and dirty solution using:

  • A gadget with content type=”url”.
  • An {include-random} macro in Confluence.

On my JIRA dashboard, the gadget shows a random tip on each refresh:

Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way

The gadget XML is very very simple:

<?xml version="1.0" encoding="UTF-8"?>

<Module>
<ModulePrefs title="JIRA tips (URL gadget)"
height="400"
scrolling="true">
<Require feature="dynamic-height"/>
</ModulePrefs>
<Content type="url" href="http://my.Confluence.Server:8090/display/MYSPACE/MYPAGE" />
</Module>

In Confluence, we have:

  • A parent page with the following content:
    {include-random:MYPAGE|nopanel}
  • And a number of child pages, each one containing a single tip.

It’s not an OpenSocial gadget, but rather a gadget with a content type of “url”. The URL given is the address of the Confluence page that contains the {include-random} macro.

2. The HTML-type gadget grabbing HTML from a Confluence page

This is a quick and dirty solution using:

  • A gadget with content type=”html”, i.e. an OpenSocial gadget, but without REST. Instead it just gets the HTML from a Confluence URL. Next stage would be to parse the HTML to isolate the content of the wiki page.
  • An {include-random} macro in Confluence.

On my JIRA dashboard, the gadget currently shows the HTML for the full page and without special styling:

Another Atlassian FedEx Day and a Confluence gadget on the way

If it’s worth pursuing this type of gadget, I need to:

  • Parse the HTML to get only the page content.
  • Apply a style sheet.

3. The OpenSocial gadget using Confluence REST API

This is supposed to be the final, walking talking solution using:

  • A full OpenSocial gadget.
  • The Confluence REST API, rolling through all the child pages of a given parent page.
  • Something to convert the wiki markup into HTML.

At the moment, it’s still a quick and dirty solution using:

  • A full OpenSocial gadget.
  • The Confluence REST API, returning a single page.
  • HTML markup in the Confluence page content.

My REST gadget returns the page body as wiki markup. Here it is on my JIRA dashboard:

Another Atlassian FedEx Day and a Confluence gadget on the way

I don’t have time in FedEx to parse the wiki markup. So I cheated completely and put the HTML directly onto the Confluence page. So here’s what the gadget shows now in JIRA:

Another Atlassian FedEx Day and a Confluence gadget on the way

Of course, the Confluence page looks like nothing on earth:

Another Atlassian FedEx Day and a Confluence gadget on the way

I’d like to pursue the REST solution. I still need to:

  • Retrieve the child pages of the given page.
  • Render the wiki markup.

Bits and pieces

At the moment all three of my gadgets consist entirely of Javascript, XML and HTML. So the whole gadget is contained in the XML gadget spec. None of them (yet) requires a plugin. Gadget XML can be served from anywhere. I’ve stored mine as attachments to a Confluence page and serve them from there.

Phew

That’s Atlassian FedEx Day for you — quick and dirty and fun. Within the next few days, I’ll post a full report on our documentation wiki (CAC) that will probably include the gadget code (if I’m feeling brave enough to expose that to the world). I hope you’ve enjoyed reading about it and learned something along with me. 🙂

Update on 1 Feb 2010: I’ve posted the “Atlassian FedEx Delivery Note” for my project on our documentation wiki now too. It contains the gadget code: ShipIt 13 Delivery – JIRA Tips Gadget. (Updated March 2013: FedEx Day is now called ShipIt Day.)

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: