How to embed Twitter streams and prepopulate tweets in your document

Sunday, 02 January 2011 04:04

It’s holiday season and I’ve been playing with Twitter again. You can do some pretty cool things with it, and it’s surprisingly easy even if you don’t have a wiki. Imagine putting other people’s words onto your pages, dynamically, as the people write them. Or having your document suggest a tweet that your reader may like to send.

You may have already seen a bit on this blog about Twitter and technical documentation. In past months I’ve written about our experiments with Twitter using the tools provided by Confluence, the wiki that hosts our documentation. That led me to wonder how easy it would be to integrate Twitter into online documentation that is not hosted on Confluence.

Hence this post. It assumes your documentation is HTML-based. The post is more of a “how to” than a “why on earth would you want to”. But since the latter is also a valid question I’ve included links to my earlier posts explaining what we’ve found Twitter useful for.

Embedding a live Twitter stream onto a page

You can embed a live Twitter stream onto a web page using HTML and a Twitter widget. Twitter supplies the widgets, which are bits of Javascript and HTML ready-made to your specifications. To make your own widget, go to the Twitter widget builder. There are a few different types of widget that you can build, such as a search widget, a profile widget, a favourites widget, and so on.

How?

Go to the page of Twitter widget builders and pick the widget you want.
Supply the search terms, title and caption as prompted.
Optional: Tweak the colours and other settings.
Click “Finish & Grab Code”.
Copy the code supplied and paste it into your document, blog post or other web page.

Example

I went to the search widget builder and entered the following information:

Search Query: “chocolate”
Title: “Tweets about”
Caption: “Chocolate”

I clicked “Appearance” and tweaked with the colours. Then I clicked “Finish & Grab Code“. The widget builder coughed up some JavaScript in an HTML <script> block, which I copied and put into a very simple HTML wrapper like this:

<HTML>
<BODY>
<h2>Testing my Twitter widget</h2>
<script src="http://widgets.twimg.com/j/2/widget.js"></script>
<script>
new TWTR.Widget({
 version: 2,
 type: 'search',
 search: 'chocolate',
 interval: 6000,
 title: 'Tweets about',
 subject: 'Chocolate',
 width: 250,
 height: 300,
 theme: {
 shell: {
 background: '#8c4ca1',
 color: '#ffffff'
 },
 tweets: {
 background: '#e8c1e8',
 color: '#444444',
 links: '#cf6514'
 }
 },
 features: {
 scrollbar: false,
 loop: true,
 live: true,
 hashtags: true,
 timestamp: true,
 avatars: true,
 toptweets: true,
 behavior: 'default'
 }
}).render().start();
</script>
</BODY>
</HTML>

I saved it as a text file called “TestTwitterWidget.html”. Here’s what the page looks like when I open it in my browser (Firefox):

Embedding Twitter streams into your documentation

The above picture is a static image, but the Twitter widget is not static when shown on your page. Instead, the tweets keep rolling downwards as each new one comes in. The widget buffers the tweets and displays them continuously. By default, it will re-display old tweets to keep the display moving. You can configure this behaviour.

The search I used above is very simple. Twitter offers more advanced search criteria, so that you can display the tweets that are relevant to your documentation. One of the most useful searches is to select tweets containing a given key word or hash tag.

What if you don’t have access to the raw HTML of your document?

Some content management systems and other platforms supply a way of safely incorporating a widget into a web page, even if they don’t give you access to the raw HTML.

On Confluence wiki, use the Widget macro.
WordPress offers a number of Twitter plugins.
I don’t know the details of other platforms. Let me know if you do.

How could a Twitter stream be useful in technical documentation?

One way is to encourage people to tweet hints and tips about your product, and then publish a live Twitter stream on a page in the documentation so that readers can benefit from each others’ ideas. I wrote a post about our experiments with hints and tips via Twitter.

Suggesting the words for a tweet, with prepopulated tweets

It can be fun and/or useful to give your readers something to say and encourage them to say it in a public forum like Twitter. This gives them the opportunity to involve their community, their followers, in what they’re doing and in your product or documentation. It’s even better if they have the option of using the words you suggest, changing those words or deciding not to use them at all.

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 Twitter’s “Tweet” (or “Update”) button as usual.

How?

Add an HTML link on your documentation page, pointing to the reader’s Twitter “home” page.
Specify a “status” parameter in the URL, containing your suggested text.

Example

<a href="http://twitter.com/home?status=Hallo world">
Say hallo to the twittersphere
</a>.

Here it is as a link – click it to see it in action:

Say hallo to the twittersphere.

URL-encoding special characters in prepopulated tweets

If your message includes funny characters, such as a # sign, then you will need to URL-encode the message. For example, if you wanted to prepopulate a tweet with “Hallo world #testing” you would use this code:

<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: The URLEncode and URLDecode page from Albion Research.

How are prepopulated tweets useful in technical documentation?

We’ve used prepopulated tweets in a series of documents that make up a complex installation and configuration guide. Because the set of procedures is rather tiresome to carry out, we decided to turn the guide into a challenge, a game where the players get the job done and enjoy a sense of camaraderie with other people who are going through the procedures at the same time. We called the guide “Here be Dragons”. If you want to know more about it, have a read of my blog post, I got dragons and tweets in my documents.

I haven’t yet tried any other way of using prepopulated tweets in documentation, but I’m sure it’s out there!

Here’s an idea: Use Twitter as a public forum for gathering feedback on our documentation. That’s certainly out there. We could put prepopulated tweets in the footer of each page, offering the reader various options for tweeting their feedback:

This documentation <<page-URL>> #myKeyWord needs X.
Found a useful page <<page-URL>> #myKeyWord. It helped me X.
Impressed with the awesome documentation on creating widgets <<page-URL>> #myKeyWord.

Ask the reader to supply the text for “X”. We can collate the feedback by gathering all tweets containing the key word “#myKeyWord”. What’s more, anyone else can gather that feedback too. I guess we’d need to be fairly confident about the quality of our documentation. But what a great way to build community spirit!

Other Twitter widgets

Twitter offers other nifty widgets, such as one that displays your profile and all your own tweets, or a list of tweets that you have marked as your favourites, or tweets by a given list of people that you follow.

More in-depth Twitter integration

For more in-depth Twitter integration on your website, take a look at this easy-to-absorb page on Twitter’s @Anywhere platform. I haven’t tried it, but it looks easy enough and quite a lot of fun.