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


Published on

Presentation for the Sydney Technical Communicator's Group, 4 May 2001. Subject: Using Twitter in and around your documentation.

Published in: Career, Technology, Business
1 Comment
1 Like
  • Hallo all
    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:
    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
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Speaker’s notes: What’s in this presentation This session is all about using Twitter in and around your documentation. Tweeting the release notes Tips submitted to Twitter by all and displayed in the documentation. An example of a game wrapped around the documentation, plus interactivity via Twitter and forums: the Dragon Slayer documentation. We’ll also take a very brief look at other ways a technical communicator may find Twitter useful – outside the documentation. It’s not all about the doco! Let’s get started: See what Twitter is. Look at some of the linguistic conventions that have sprung up in people’s tweets. Tweet, right here, right now.
  • Speaker’s notes: Twitter Twitter is one of the main ways people share information. People send and read tweets on the web, their phones, Facebook, email, RSS, desktop apps... Anywhere, anytime. What is Twitter: Twitter is a web service that allows you to send short messages to anyone who is interested in reading them. You can sign up for a free account at http://twitter.com. Then just type in your message where Twitter asks “What are you doing?” and click “Update”. Bob’s your uncle, you’ve tweeted. T o read other people’s tweets, you “follow” the people. Twitter will send you the tweets of the people you are following. Why: Reach people where they are. One of the most magical aspects of Twitter is that people don’t have to go to Twitter.com to use it. People read tweets via email, via desktop widgets and apps, on their phones and so on. Short and sweet. People will read and absorb short, punchy messages. Fun.
  • Speaker’s notes: Twitter linguistics and conventions More complex tweets use accepted conventions: “ @” symbol to speak directly to another person e.g. in reply to their tweet. “ #” symbol to denote a particular topic. Called a “hash tag”. “ RT” means “re-tweet”. You are repeating someone else’s tweet because you like it. “ Tiny URLs” or shortened URLs, to reduce the number of characters in your tweet. 140 characters is the limit for the text in a tweet. You can get shortened URLs from various web sites like tinyurl, bit.ly, etc. Aah, metadata! That’s something we technical writers know and respect. How can we make use of these conventions?
  • Speaker’s notes: Twitter linguistics and conventions Tweet: How many Sydney tech writers are a-tweeting? #SydneyTechComm Search: http://search.twitter.com/search?q=SydneyTechComm
  • Speaker’s notes: Introducing the topic We know that companies are becoming more social. Engaged customers buy more, are more satisfied with the product, and are more likely to help each other. Similarly, engaged readers are more likely to keep coming back to the documentation, are more satisfied with the documentation, and will use the documentation as a tool to help each other. Documentation is the face of the company. People come to the documentation looking for answers. How can you make your documentation a living, interactive hub where people can come to find answers, talk to you, swap techniques and help each other? People are already discussing us and our documentation via Twitter and other social media. Let’s join the conversation, see what they’re saying, and show them that we care.
  • Speaker’s notes: Twitter as medium for release notes Each tweet: Reflects a major point in the release notes. Links to the "real" release notes. Contains a hash tag to tie the tweets together. Why use a #-tag? It provides a way for readers at any time to see a collection of such related tweets. A collection of release highlights is… the release notes. That’s how we use Twitter as a medium for our release notes. Ta da ♪ ♫ Also in the above slide: People have re-tweeted our tweet. Other people have added extra tweets using our has tag – one in Dutch! A screenshot of the same Twitter stream on an iPhone. Small chunks of information (tweets) are: Easy to digest. Shareable. Interactive and conversational. Useful for drawing people to the documentation. Is there a chance people will add unfavourable information to your stream? Oh yes! But that’s all part of it. It’s up to you to respond. Keep the conversation going.
  • Speaker’s notes: Tips via Twitter We encourage readers to submit hints and tips via Twitter. The #-tag is the key. For our product called Confluence: #ConfluenceTips For JIRA: #JIRATips Take it a step further: We have embedded the Twitter stream into a documentation page. So people can see the tweets out there in the Twittersphere. They can also see them in the documentation. What’s more, they can see their own name and tweets in our documentation!
  • Speaker’s notes: The Dragon Slayer – the problem We provide a number of products that can work together to provide a useful, pleasing development environment: bug tracker, agile project management tool, wiki, gadgets, source repository navigator and continuous integration tool, all tied together by a unified user management and single sign-on tool. But installation and configuration are complex: The applications were not originally designed to work together. The applications were developed at different times by different teams, some not even Atlassian. The points of integration are varied, some quite deeply embedded in the product and others simply a gadget. We use newly emerging technologies, such as OpenSocial gadgets, which change as we develop on top of them. So the Dragon Slayer documents have a four-fold purpose: Lead you through the installation and configuration of a unified suite. Demonstrate the cool integration possibilities, by showing an example of each type. Highlight to us the steps required and the pain points that we should address first. Allow us to track the improvements in the procedure itself. Convert the pain to fun. Documentation is a good way of fixing a painful procedure in the short term. Because this procedure is so painful, we decided to turn it into a game and make it fun.
  • Speaker’s notes: Dragon Slayer – the game The game: 9 stages Charlie starts out with very little clothing or other accoutrements. Actually, he’s naked, and has just a staff. “ Charlie” is the nickname for the dude in the Atlassian logo. As the reader works their way through the steps, Charlie acquires a piece of armour or a bigger weapon. The rewards: Charlie acquires clothing and armour. The person feels part of a community of “dragon slayers”. Camaraderie and contact with Atlassian. The person gets a difficult task done by following step-by-step, top-down instructions. Sense of achievement, conquering the dragon and telling everyone else how much they have managed to do too. Fun. T-shirt.
  • Speaker’s notes: The Dragon Slayer pages Format: Fun stuff is at top and bottom of page. In between is solid, well-tested “how to” information.
  • Speaker’s notes: Dragon Slayer interactivity Interactivity: Tweet directly from the wiki page. Real-time display of tweets on the page. Link to Twitter for people who want to follow the other dragon slayers via the Twitter web interface. Link to forum, where people can meet other dragon slayers and help each other. The Atlassian support team also monitors the forum and helps with problems.
  • How to add a hyperlink to your page, that suggests some words for people to tweet.
  • Speaker’s notes: Dragon Slayer Twitter stream People love a game. The suggested tweets are funny, in context and a call to arms. Other people join in – more hijacking of the twitter hash tag. When I got into the office on the first day after publishing the Dragon Slayer documentation, I saw the Twitter stream and thought, “ Wow, people are actually doing it. They’re doing the dragon quest and tweeting all over the show!” It was an awesome feeling!
  • Speaker’s notes: There’s more to Twitter This session was all about using Twitter in and around your documentation. But there are other ways to use Twitter as a technical writer: Conversation with people all over the world. Swapping information with other technical writers. Fun Twitter chat.
  • Speaker’s notes: Tech comm chat on Twitter Twitter chat is what happens when a group of people get together at the same time on Twitter and chat about a given subject. They use tweets as the medium for their utterances. There’s a group of people that get together regularly to chat about technical communication. We use the hash tag #tcchat. Next session: Thursday 5 May at 11am, Sydney time. (The organiser is in California. For them, it’s 6pm on Wednesday 4 May.) Topic for this session: Making Docs More Interactive and Interacting with Customers” Join us!
  • Speaker’s notes: How to join the #tcchat session How? Sign up for a Twitter username. Be at your desk at 11am tomorrow (Thursday 5 May). Do a Twitter search for #tcchat. Read the tweets. Go to your own Twitter home page and tweet “Hallo, I’m Sarah in Sydney #tcchat” or something similar (if you want to). Tweet your contribution to the topic (if you want to).
  • A little bird told me... about a good page in your user guide

    1. 1. A little bird told me… about a good page in your user guide Sydney CBD Technical Communicators 4 May 2011 Twitter in and around your documentation
    2. 2. About me @sarahmaddox Technical writer at Atlassian http://www.youtube.com/travellingworm http://www.linkedin.com/in/sarahmaddox http://www.flickr.com/people/31065906@N08/ http://ffeathers.wordpress.com http://www.facebook.com/#!/sarahmaddox.fb
    3. 3. <ul><li>Introduction to Twitter </li></ul><ul><li>Twitter as a medium for release notes </li></ul><ul><li>Tweeting hints and tips </li></ul><ul><li>Interactivity in your documentation: Dragon Slayer </li></ul><ul><li>Twitter and your career </li></ul>In this presentation Twitter Docs You
    4. 4. What is Twitter? Max 140 characters People really do tweet about lunch Show me
    5. 5. But that’s gobbledegook! Conventions add meaning, like @, RT and # Twitter linguistics and conventions
    6. 6. <ul><li>Tweet a message </li></ul><ul><li>Include the # tag in your tweet </li></ul><ul><li>See the Twitter stream: http://search.twitter.com/search?q=SydneyTechComm </li></ul>Let’s tweet – right now #SydneyTechComm That’s metadata! We know all about that!
    7. 7. Why use Twitter in your documentation? <ul><li>The social enterprise </li></ul><ul><li>Engaging customers and readers </li></ul><ul><li>Documentation as a living, interactive hub </li></ul><ul><ul><li>Our readers are already discussing us on social media </li></ul></ul><ul><ul><li>Let’s join the conversation </li></ul></ul><ul><ul><li>Hear what they have to say </li></ul></ul><ul><ul><li>Show them we care </li></ul></ul><ul><ul><li>Use the media for our own good </li></ul></ul>
    8. 8. Tweeting your release notes Ooo-er, did I tweet that? Bite-sized chunks Interactive Shareable On an iPhone
    9. 9. Live Twitter stream embedded into the page Tips via Twitter #ConfluenceTips Show me
    10. 10. <ul><li>Cool integrated development suite but </li></ul><ul><ul><li>Complex installation and configuration </li></ul></ul><ul><ul><li>Emerging technologies (gadgets, OpenSocial) </li></ul></ul><ul><li>Dragon Slayer docs to the rescue </li></ul><ul><ul><li>Lead you through the setup </li></ul></ul><ul><ul><li>Demo the cool integration possibilities </li></ul></ul><ul><ul><li>Document the steps and the pain </li></ul></ul><ul><ul><li>Track the improvements </li></ul></ul><ul><ul><li>Turn pain to fun </li></ul></ul>Dragon Slayer – the problem
    11. 11. <ul><li>9 stages, each with many steps </li></ul><ul><li>Rewards: </li></ul><ul><ul><li>Charlie’s clothing and armour </li></ul></ul><ul><ul><li>Fun and camaraderie with Atlassian and other dragon slayers </li></ul></ul><ul><ul><li>Getting the complex task done </li></ul></ul><ul><ul><li>Sense of achievement </li></ul></ul><ul><ul><li>T-shirt, fun </li></ul></ul>Dragon Slayer – the game
    12. 12. Fun stuff is at top and bottom of page Good solid, well-tested “how to” instructions in between Dragon Slayer pages
    13. 13. Live Twitter stream on the page Auto-tweeting link Dragon Slayer interactivity
    14. 14. Adding an auto-tweeting link http://twitter.com/home?status=My status
    15. 15. People love a game Dragon Slayer Twitter stream Show me
    16. 16. <ul><li>Conversation </li></ul><ul><li>Swapping information </li></ul><ul><li>Ideas </li></ul><ul><li>Fun </li></ul>There’s more to Twitter
    17. 17. Tech comm chat on Twitter <ul><li>Tag: #tcchat </li></ul><ul><li>Next session: </li></ul><ul><li>Thursday 5 May, 11am (Sydney time) Wednesday 4 May, 6pm (US Pacific time) </li></ul><ul><li>“ Making Docs More Interactive and Interacting With Customers” </li></ul>Thank you Julie Norris
    18. 18. How to join the #tcchat session <ul><li>Sign up for a Twitter username (optional) </li></ul><ul><li>Log in to Twitter at 11am tomorrow </li></ul><ul><li>Do a Twitter search for #tcchat </li></ul><ul><li>Read the tweets </li></ul><ul><li>Go to your own Twitter home page and tweet Hallo, I’m Sarah in Sydney #tcchat or something similar (optional) </li></ul><ul><li>Tweet your contribution to the topic (optional) </li></ul>
    19. 19. Contacting me <ul><li>Email: [email_address] </li></ul><ul><li>Twitter: @sarahmaddox </li></ul><ul><ul><li>http://twitter.com/sarahmaddox </li></ul></ul><ul><li>LinkedIn: http://au.linkedin.com/in/sarahmaddox </li></ul><ul><li>Blog: http://ffeathers.wordpress.com </li></ul><ul><li>Other blog: http://travellingworm.wordpress.com/ </li></ul>
    20. 20. References 1 <ul><li>Download this presentation: http://bit.ly/iEzdkV </li></ul><ul><li>Twitter </li></ul><ul><ul><li>Twitter: http://twitter.com/ </li></ul></ul><ul><ul><li>Twitter’s note about the limitations of the search: http://apiwiki.twitter.com/Things-Every-Developer-Should-Know#6Therearepaginationlimits </li></ul></ul><ul><ul><li>A site that will URL-encode your text for you: http://www.albionresearch.com/misc/urlencode.php </li></ul></ul><ul><li>Twitter as a medium for release notes </li></ul><ul><ul><li>Blog post, including an introduction to Twitter and many useful comments from readers: http://ffeathers.wordpress.com/2009/06/08/twitter-as-a-medium-for-release-notes/ </li></ul></ul>
    21. 21. References 2 <ul><li>Hints and tips via Twitter </li></ul><ul><ul><li>Our “Tips via Twitter” page for the JIRA documentation. http://confluence.atlassian.com/display/JIRA/Tips+via+Twitter </li></ul></ul><ul><ul><li>Our “Tips via Twitter” page for the Confluence documentation. http://confluence.atlassian.com/display/DOC/Tips+via+Twitter </li></ul></ul><ul><ul><li>Blog post about tips via Twitter: http://ffeathers.wordpress.com/2010/06/22/hints-and-tips-via-twitter/ </li></ul></ul><ul><ul><li>Rewarding people for tweeting hints and tips: http://ffeathers.wordpress.com/2010/08/14/badges-for-twitter-tips-and-thanks-to-technical-writers/ </li></ul></ul><ul><li>Tech comm chat </li></ul><ul><ul><li>Home page http://www.facebook.com/TCchat1#!/TCchat1 </li></ul></ul><ul><ul><li>Guide http://www.2morodocs.com/2010/09/twitter-chats-101/ </li></ul></ul>
    22. 22. References 3 <ul><li>Twitter for interactive documentation </li></ul><ul><ul><li>The Dragon Slayer documentation: http://confluence.atlassian.com/display/ATLAS/Here+Be+Dragons </li></ul></ul><ul><ul><li>Blog post about the Dragon Slayer documentation: http://ffeathers.wordpress.com/2009/10/10/i-got-dragons-and-tweets-in-my-docs/ </li></ul></ul><ul><ul><li>Blog post on how to embed Twitter streams and prepopulate tweets: http://ffeathers.wordpress.com/2011/01/02/how-to-embed-twitter-streams-and-prepopulate-tweets-in-your-document/ </li></ul></ul>The end – thanks folks!
    23. 23. Screenshot
    24. 24. Screenshot
    25. 25. Screenshot
    26. 26. Screenshot
    27. 27. Screenshot
    28. 28. Screenshot
    29. 29. Screenshot
    30. 30. Screenshot
    31. 31. Screenshot
    32. 32. Screenshot