How to embed Twitter streams and prepopulate tweets in your document

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?

  1. Go to the page of Twitter widget builders and pick the widget you want.
  2. Supply the search terms, title and caption as prompted.
  3. Optional: Tweak the colours and other settings.
  4. Click “Finish & Grab Code”.
  5. 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

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?

  1. Add an HTML link on your documentation page, pointing to the reader’s Twitter “home” page.
  2. 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.

About these ads

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 2 January 2011, in Confluence, technical writing and tagged , , , , , . Bookmark the permalink. 27 Comments.

  1. Great idea, Sarah! I see you’re out there pushing the envelope, as always. Thanks for the comprehensive info and sample code. I’ll have to try this out -

  2. Hi Sarah.
    I found a shout out to Atlassian in a youtube video, and thought you might like to see it: http://www.youtube.com/watch?v=u6XAPnuFjJc

    Keep up the interesting tweets!

    Paul.

    • Hallo Paul

      Thanks! It’s a great video, though a little bit long. Still, I love the way they’ve put it together, and the shout out to Atlassian is just wow. :)

      What does the handle “64 Gunna” mean? Just curious.

      Cheers
      Sarah

  3. Hallo all

    Update on how to create an auto-tweeting link:

    The Twitter API has changed, meaning that we need to change the URL that we use for auto-tweeting links. The changes seem to require the following:
    1) Remove the word “home” from the URL. Instead of this:
    “http://twitter.com/home?status=My status”
    It’s now this:
    “http://twitter.com/?status=My status”
    2) If you URL-encoded your message, then you need to get rid of all the plus signs but leave the special characters encoded. So, instead of this:
    “My+status+encoded+%23techcomm”
    You’d now have this:
    “My status encoded %23techcomm”

    Here’s a full example of something that works. Let’s say you want to tweet “My status encoded #techcomm”. This is your URL:
    “http://twitter.com/?status=My status encoded %23techcomm”

    Cheers, Sarah

  4. trying to find out what protection i can offer in an embedded widget has resulted in considerable hair loss.

    your help was not.

    can i offer any filtering, blocking of scum?

  5. Hi, i tried this but the browser does not show the widget. just the header. what could have been missing in my procedures?

  6. Sarah, I was unable to successfully embed one of these widgets anywhere on my Posterous blog (post, page, skin). Without digging too deep, I think Posterous strips parameters or blocks elements. I do however regularly embed individual tweets in a blog post – no issues there.

    I also tried to embed a widget on Tumblr, and there I was able to do it on an individual page but not in the sidebar where I really wanted it.

    I don’t know if those issues are Posterous and Tumblr specific, or if they’re just specific to the themes I’m using on those sites. You would think Posterous would have better Twitter integration now that Twitter owns them…

  7. Cold you tell me that how to increase number of tweets in the main page..

    Thank you all.

  8. Out of the many that I tried this one worked!

  9. This actually worked for me. Anybody know how to make this responsive instead of a fixed width? It wreaks havoc on the mobile version of my site.

  10. This method may have an issue after March 5, 2013 with the change in Twitter’s API to version 1.1.

  11. If you’re displaying other people’s tweets, how do you control negative feedback? For example, someone can include vulgar language with the word “chocolate” so it can end up being displayed on the site. Any way to filter things like that? Thanks.

  12. Can I get the user details like username from above Twitter streams and prepopulate tweets . any help ??
    Thanks,
    Absar

  13. This is the best and easiest way to display twitter data in your website with latest version 1.1:

    http://matifk.spxwaves.com/how-to-show-twitter-timelines-on-website-with-latest-version-1-1/

  14. Reblogged this on Bellropespider and commented:
    Recommended reading for webmasters….

  15. It doesn’t work on my site

  1. Pingback: Tweets that mention How to embed Twitter streams and prepopulate tweets in your document « ffeathers — a technical writer’s blog -- Topsy.com

  2. Pingback: Online Creative Clusters « Dragonfly Scrolls

  3. Pingback: Let Your Customers Tweet in Your Documents « LexPower

  4. Pingback: Help write a Twitter guide for technical communicators « ffeathers

  5. Pingback: Research into making a live feed of tweets | ConvergentMedia

  6. Pingback: Online Creative Clusters | Kim Koning

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 )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 1,454 other followers

%d bloggers like this: