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:


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.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 22 June 2010, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , . Bookmark the permalink. 15 Comments.

  1. Sarah, I like this a lot, and I hope you’ll report back to us on how well it goes.

    To satisfy my curiosity, I searched in the Confluence documentation and found Tips via Twitter as a second-level node under Confluence Resources in the navigation pane. In other words, I probably wouldn’t have found it had I not been looking for it. What led you to locate the link there rather than in a more prominent place — say, a big blue button at the bottom of each topic? (Or did I miss a more prominent link because I was too busy looking under rocks?)

    • Hallo Larry
      That’s a good point. Originally I’d thought to add a mini Twitter stream to the doc home page, with a link through to the Tips via Twitter page. But on review with the other tech writers, this idea was scotched because the page was not consistent with the other product home pages and also because it looked cramped. I didn’t think of adding a link or button on each page. I’ll put together some designs and discuss it with the team. Thank you for the idea! And thanks for the encouragement too.
      Cheers, Sarah

    • Hallo again Larry

      Following up on your excellent point, I’ve rearranged the pages to highlight the fact that community contributions are welcome. I’ve created a page at the top level of the hierarchy:

      The “Tips via Twitter” page is now a child of that page, and so is “Tips of the Trade”.

      What’s more, we now have a shiny new button in the footer, that directs people to the page about contributing to the docs.

      Thanks so much again for your comment!

      • The changes look great, Sarah. With these additions, you’re now sending a clear message to your readers: We want you to partner with us to make our documentation even better.

  2. Hi Sarah,

    What an innovative approach…I will follow how incorporating user-generated content (via tweets) into your technical documentation works out…Even if you have one or two dedicated users contributing, you’re still getting all that feedback on the doc & your products…and just putting yourself “out there” like that says so much about Atlassian’s involvement and interest in its customers. Kudos to you! Also, this example seems very much in the spirit of Scriptorium’s trends webcast, and our previous blog conversation about creating more of a positive emotional & interactive experience with our customers (a la Ellis Pratt’s presentation).

    Thanks for sharing your experiment…Wishing you a happy outcome!


    • Hallo Peg
      Thank you, it means a lot having enthusiastic comments from fellow tech writers. It’s a great deal of fun, putting us “out there”. 😉 I am going to need to think up extra ways of encouraging people to tweet, though, because the stream does dry up. I’ll put my “thinking hat” on. (Since our innovation sprint, thinking caps have been somewhat upgraded.)

  3. Hi Sarah,

    I’ve long been thinking about leveraging the power of social networking and end-user documentation. It seems that you have found something very interesting indeed.

    I’ve got some tips and hints:

    1. How about a “Tip of the Day”? I know all tips are important, however I always felt that there is something about it that attracts users.

    2. How about have a small lil counter besides the twitter user name denoting the number of tips? For example, John (23 Tips via Twitter), Sarah (13 Tips via Twitter and so on). I for one would like to know the score for sure!

    3. To encourage users to tweet tips, I would consider giving them a badge of honour which they can proudly display on their blogs or any social networking site. A badge which says “I share my Tips via Twitter. Do you?” or something similar. However, this badge of honour should be given only to users who are consistently tweeting greats useful tips, a power user and so on. You will have to set the rules.

    Hope this helps.


    • Hallo Jay

      Wow, what brilliant ideas! The first two are difficult to achieve, with the way our Twitter widget interacts with Twitter.

      For the “Tip of the Day”, I’ve been thinking along the lines of a gadget that reads a wiki page, containing a random tip. People could put the gadget anywhere that supports gadgets, such as Gmail or a JIRA dashboard. But that’s sort of bypassing Twitter.

      Your second idea, of showing a count of tweets with a specific tag per user, is awesome. It would need a bit of coding, to get it into a Twitter widget that we could use in the docs.

      And I totally love your third idea, of a badge people can display on their blogs etc. Way to go Jay! I’ll have a word with our design team and management, to see what people think.

      Thank you so much!

  4. Love it. It’s a great way to get customers involved and rallying around a product. Confluence-aholics not-so-anonymous 🙂

  5. Update: Badges for Twitter tips (thanks Jay) and highlighting the community aspects of our documentation (thanks Larry):

  6. Sarah,

    This is extremely cool. I always enjoy reading about your experiences and the Confluence wiki. I think this use of Twitter is extremely valuable. In fact, I’m completing research for my graduate degree on the use of Twitter in tech communication (and how undergrads can prepare to use it). Would you mind if I mentioned this experiment?


  1. Pingback: Your Docs: Thought about Adaptability? — 2moroDocs

  2. Pingback: Technical Documentation through Twitter? | Technical Communication Center

  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 )

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: