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?
- 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.
Posted on 2 January 2011, in Confluence, technical writing and tagged Confluence, social media, technical communication, technical documentation, technical writing, Twitter. Bookmark the permalink. 27 Comments.
ffeathers 
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 –
Hallo Julie
Thanks so much! Let me know how it goes and if it gives you any ideas. 🙂
Cheers, Sarah
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
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
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?
Hi, i tried this but the browser does not show the widget. just the header. what could have been missing in my procedures?
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…
Hallo Daniel
Thanks for shari ng the results of your research! The information about support in different platforms is very useful. It would make a great addition to our burgeoning Twitter guide for tech comm: http://wikitechcomm.onconfluence.com
Would you like to flesh out this page:
https://wikitechcomm.onconfluence.com/display/DOC/Displaying+a+live+Twitter+stream+on+a+page
Or perhaps add another page specifically for platform-specific details?
🙂
Cheers,
Sarah
Cold you tell me that how to increase number of tweets in the main page..
Thank you all.
Out of the many that I tried this one worked!
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.
Just changed the width variable to ‘auto’ and it fits the responsive wordpress template perfectly. Thanks you for posting this.
This method may have an issue after March 5, 2013 with the change in Twitter’s API to version 1.1.
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.
Hallo Robin
You’re right, we’re at the mercy of the general public when displaying tweets. I monitor our Twitter streams and haven’t seen any vulgar language yet. This is primarily because of the subject matter of the tweets – technical, and therefore less likely to attract that sort of language. I don’t know of an easy way to filter it out automatically. You could put all sorts of exclusions into your Twitter search string via the “-” operator, but that would only exclude the words you’ve thought of.
Here’s the information about the advanced Twitter search: https://support.twitter.com/groups/31-twitter-basics/topics/110-search/articles/71577-how-to-use-advanced-twitter-search#
Cheers, Sarah
Thanks Sarah!
Can I get the user details like username from above Twitter streams and prepopulate tweets . any help ??
Thanks,
Absar
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/
Reblogged this on Bellropespider and commented:
Recommended reading for webmasters….
It doesn’t work on my site
Pingback: Tweets that mention How to embed Twitter streams and prepopulate tweets in your document « ffeathers — a technical writer’s blog -- Topsy.com
Pingback: Online Creative Clusters « Dragonfly Scrolls
Pingback: Let Your Customers Tweet in Your Documents « LexPower
Pingback: Help write a Twitter guide for technical communicators « ffeathers
Pingback: Research into making a live feed of tweets | ConvergentMedia
Pingback: Online Creative Clusters | Kim Koning