Help write a Twitter guide for technical communicators

Would you like to help write a guide to using Twitter, especially for technical writers? At the same time, you can try out Confluence wiki and learn from other tech comm Twitter experts.

An interesting fact: The top post on this blog is a technical guide to prepopulating tweets and embedding tweets in a document. (Here’s the post.) It has received more than 13 thousand visits to date. The next most popular post, about writing REST API documentation, has received 11 thousand visits and has been around for two years longer than the Twitter post.

People really want to know about this stuff. We can use Twitter in our documentation, in our careers, and in communication with our peers. How great would it be if we had a technical communicator’s guide to Twitter, written and regularly updated by us!

That idea came to me while I was writing my book, Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. Then I took the idea a step further and made the writing of the guide a project that Ganache, the hero of the book, was tackling. Ganache wrote part of the guide. The screenshots are in the book. She also wrote some stubs for pages that she thought would be useful in the guide.

Now it’s up to us to complete the guide, and to keep it up to date.

How to contribute to the Twitter guide for technical communicators

Go to the wiki, at https://wikitechcomm.onconfluence.com/display/CHAT/About+this+site, and follow the instructions to get a username. It’s free, and you can choose any username that hasn’t yet been taken. You will need to give an email address, but the email address won’t be shown to other users (unless you make your username the same as your email address).

Read the Twitter guide, and fill in the missing details. All contributions welcome. You can edit the existing pages or add new ones. Other people will probably edit your pages too. It’s a wiki, and all logged-in users have permission to update the pages. Content is licensed under a Creative Commons copyright, as specified in the footer of each page.

Who else is on the wiki?

Your name will appear along with the others who are already there. I’m there, and so is Ganache.  🙂

Wiki-Wiki Shuttle

I’ve just spent a couple of days on the island of Oahu, in Hawaii, on my way to and from the STC Summit 2012. I couldn’t resist taking this snap:

Tweet at us now – Sydney technical communicators meeting at Atlassian on 4 May

The next meeting of the Sydney CBD technical communicators group is on Wednesday 4 May. This month it will happen at the Atlassian offices, and I’ll be presenting a session on Twitter in and around your documentation. Can you come? Lunch is on the house! Even if you’re not in Sydney, it would be great if you can tweet at us: #SydneyTechComm. Tweet now, or any time before the meeting. I’d love to show the group a stream of tweets from technical communicators all over the world.

Thank you to Bede Sunter for all his hard work in arranging these great monthly sessions! He has asked me to speak this month, and we’re holding the session at the Atlassian offices.

Date and time: Wednesday 4 May, 12:30 to 1:30pm.
Place: Atlassian offices, 173-185 Sussex Street, Sydney. (Google maps.)
Lunch: Free. Thank you Atlassian!
Who can come: Anyone interested in technical communication.
RSVP: Drop a comment on this blog post, and I’ll email you.

The presentation

You can download the presentation from SlideShare.

I’ll give a talk about using Twitter in and around your documentation.

A little bird told me… about a good page in your user guide

What’s all the fuss about Twitter, and how can I get involved? Do I even want to? In this session, Sarah will give a quick introduction to Twitter and the conventions that have sprung up in the tweeting community. Then we’ll see how we can use this new medium in and around our documentation:

• Twitter as a medium for release notes.
• Encouraging your readers/customers to tweet hints and tips.
• Building interaction into your documentation pages.

Come along, bring your smart phones and your clever quips. Let’s get social. 🙂

I’m trying something new, in that I’ve already published the slides on SlideShare. This means you can have a look even before the session happens. Let me know if you like seeing the slides early!

Tweet hello to the Sydney technical communicators

At the session I’ll be introducing a number of people to Twitter.

• If you’re planning to come, tweet now.
• Even if you’re not in Sydney, it would be great if you can tweet at us. I’d love to show the group a stream of tweets from technical communicators all over the world. You can tweet now if you like — the tweets will show up in the Twitter stream next week too.

If you haven’t used Twitter before, you can sign up for a free account at the Twitter website . You can use any name you like. It doesn’t have to be a real name.

Say hello and tell us where in the world you are, using this hash tag:

#SydneyTechComm

Some example tweets:

Looking forward to the Sydney tech communicators meeting on 4 May http://bit.ly/iEzdkV #SydneyTechComm

Sydney technical communicators tweetup 4 May FTW http://bit.ly/iEzdkV #SydneyTechComm

Hello Sydney technical writers! From a chilly Mark Twain in San Francisco #SydneyTechComm

😉

Let me know if you can come or if you can tweet

Add a comment to this post, if you like. I’d love to see you there, or see your tweet!

WritersUA 2011 – Using social media to get readers involved

This week I attended the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. On Tuesday it was my turn to present a session, called “Getting your readers involved in the documentation”. This post summarises my talk and offers you the opportunity to download the presentation in PDF form.

At Atlassian, we’ve been using social media in various ways, to make our documentation a living, interactive hub where people can find the answers to their questions, talk to us, talk to each other, and use the documentation as a tool to help each other.

Download the presentation

If you like, you can download a copy of my presentation in PDF form. I’ve put a lot of information and references into the speaker’s notes too.

• Download the slides in PDF form (1,642 KB): Getting your Readers Involved in the Documentation (slides only)
• Download the slides with notes in PDF form (1,196 KB): Getting your Readers Involved in the Documentation (slides with notes)

What’s in this post

The rest of this post is a summary of and discussion of my presentation, and of the condensed version that I showed people at the WritersUA peer showcase.

The social organisation

We know that organisations are becoming more social. Studies show that engaged customers buy more, are more likely to be satisfied with the product, and are more likely to help each other use the product.

In the same way, I’d like to propose that engaged readers will keep coming back to the documentation, are more likely to be happy with the documentation, and will use the docs as a tool to help each other.

The tools

The tools and ideas I discussed are:

• Using a wiki as the documentation authoring and publishing tool – Confluence. In our documentation and in my presentation I’m using Confluence wiki. But most of the tools and ideas are transferable to online documentation on any platform.
  • Allowing readers to add comments to the documentation pages.
  • Allowing various groups of people to edit your documentation, including community authors, all the company staff, customers, the whole wide world.
  • Using wiki permissions to determine who can do what.
  • Monitoring the updates via RSS feeds and wiki watches.
• Designing a contributor licence agreement, based on the Apache Contributor License Agreement, to protect the rights of all parties.
• Adding a Creative Commons copyright licence to the documentation pages. Ours is a Creative Commons by Attribution licence, which means that anyone can use the documentation for any purpose they like, provided they acknowledge us as the source.
• Using a web service that allows you to design an online feedback form, then grab the HTML to embed the form into your own documentation page – Wufoo. When people fill in information on your form, the data goes into the Wufoo database. You can then log in to Wufoo and see the results, get some statistics, and so on.
• Linking to blog posts written by community developers and authors from within your documentation. For example, the JIRA Tips of the Trade, the Crowd Tips of the Trade and the Confluence Tips of the Trade.
• Encouraging people to interact with your documentation via Twitter (Twitter.com).
  • Using Twitter as a medium for your release notes.
  • Encouraging people to tweet hints and tips about your products, and then taking it a step further and embedding a live stream of tweets on a documentation page. See the JIRA Tips via Twitter and the Confluence Tips via Twitter pages.
• Rewarding contributors by giving them an online badge that they can add to their blogs or other social sites.
• Organising a doc sprint. This is an event, similar to the book sprints of the opensource world, where a group of people get together for a specific period of time to write a specific set of documentation. We have held two doc sprints, with participants working in our offices and remotely all over the world. We plan to hold more.
• Bringing back fond memories of a documentation-related event, and encouraging people to join in next time, by streaming photos of the event onto your documentation page directly from Flickr. Flickr is a web service where you can upload and share photographs with your community, friends and the world.
• Building fun, a game, a challenge and interactivity into your documentation. I demonstrated at the Dragon Slayer documentation.

The Dragon Slayer Documentation

The Dragon Slayer documentation is a set of installation instructions that we created to solve a specific problem. Atlassian, the company I work for, has a great set of products that you can set up to work together as an integrated development suite. At the moment, though, the integration process is long and complex. In fact, it’s painful. The products were not originally created to work together, and we’re developing the integration incrementally. The setup process is getting easier all the time, because our developers are working to improve the process.

In the meantime, we needed some documentation that leads people through the setup process, to create a specific environment with some good simple examples of the integration possibilities. This documentation does not replace the existing installation and upgrade guides for each product. Instead, it’s an additional tool to get people started quickly when they want to set up the full suite of products.

What’s more, because the process is long and complex, we wanted to turn the pain into fun. So we challenge people to come a slay the dragon. The dragon is, of course, the setup process.

A summary of the Dragon Slayer docs:

• There are 9 stages, corresponding to 9 pages. Each stage consists of many steps.
• We’ve taken pains sure ensure that the fun stuff is at the top and bottom of the pages. In between is good, solid technical writing – “how to” steps that we test rigorously, end-to-end, before making any updates, to ensure that the entire environment will work.
• There’s a pretty picture and some funny words (shamelessly cribbed from various online translations of Dante) at the top of each page.
• At the bottom of each page, we congratulate you on your victory and tell you what you have achieved so far.
• When you start out on the dragon quest, you meet Sir Charlie of Atlassian, whom you will recognise as the dude in the Atlassian logo. He is scantily clad and has only a staff to ward off the dragon.
• As you go through the stages, Charlie acquires armour and a sword, so that he is well equipped by the time he meets the dragon in stage 9.
• When you finish the dragon quest, you get a T-shirt. (A real one.)
• During the quest, you can intereact with other dragon slayers via Twitter. We’ve crafted some funny tweets that are a call to action. If you click the “Tweet” link, we prepopulate your tweet box with those words. You can delete or change them before tweeting. We also embed a live stream of tweets on the Dragon Slayer front page, so that people can see which dragon slayers are out there right now.
• Each page also has a number of links to the dragon slayers’ forum, where you can discuss any problems you encounter and swap ideas with other people going through the procedures at the same time as you.

The plan is that the Dragon Slayer documentation will morph into a set of quick, simple steps. The dragon may disappear entirely. Or maybe not. Watch this space. 😉

The WritersUA peer showcase

I presented a condensed version of the presentation at the WritersUA peer showcase on the last day of the conference. What happens at the peer showcase is that you sit at a table for two hours, and people drop by in groups or individually to see your project. So you need just a short demonstration. I focused on our use of Twitter in and around the documentation, and specifically on the Dragon Slayer documentation.

I was completely overjoyed when I won the award for the most innovative peer showcase project at the 2011 Conference for Software UA. Thank you so much to everyone who voted for our project, and to Atlassian for giving the technical writers the opportunity to do such fun stuff in our documentation.

Bye

I hope you find the attached presentation useful. Let me know what you think, and if you’re doing something similar.

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

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.

Badges for Twitter tips and thanks to technical writers

It’s recently struck me again: There is so much creativity, generosity and enthusiasm in the technical writing community! A while ago, I let people know that I was kicking off a project called Tips via Twitter. Many technical writers commented and tweeted their encouragement and ideas. Now we’ve just started a Twitter tips stream for another of our products, and designed badges that tweeters can display on their blogs.

The badges are oh so cute. Vijayendra Darode came up with the idea and posted a comment on my earlier blog post:

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.

Thank you so much Jay! Here’s what the badges look like:

(If you want one for your blog, grab the HTML from my Atlassian blog post.)

Highlighting the fact that people can contribute to the documentation

Larry Kunz had another great idea, that we should make the community aspects of our documentation more visible. So I’ve been creating pages called “Contributing to the xxx documentation”, where “xxx” is the product name. For example, here’s the page for our JIRA bug tracker: Contributing to the JIRA documentation, and for the Confluence wiki: Contributing to the Confluence documentation.

The “Tips via Twitter” pages are now children of those pages, and so are the “Tips of the Trade” pages, where we link out to “how to” blog posts by our customers and community.

What’s more, we now have a shiny new button in the page footers, directing people to the page about contributing to the documentation:

Thank you to the technical writing community

Innovation, passion and generosity are alive and well amongst technical writers. Thank you everyone! I’ve also added a paragraph in the Atlassian blog post, letting people know that the technical writing community rocks!