Engaging readers, by Sarah Maddox – tweet @sarahmaddox 1

Engaging your readersin the documentation

Tekom tcworld23rd – 25th October 2012, Wiesbaden

How and why with social media

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 2

But nobody reads the documentation!

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 3

Why social?

The social enterprise

Social is happening anyway

How to get our readers involvedSocial media

Documentation as an emotional experience

Huh?

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 4

"Documentation as an emotional experience”

This @$$#*! documentation SUCKS!

But wait...

Weird?

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 5

"Documentation as an emotional experience”

Weird?

But wait...

I felt the earth movewhen I read your docs, mate

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 6

The death of SEO – or its rebirth?

The Death Of SEO: The Rise of Social, PR, And Real Content

http://www.forbes.com/sites/kenkrogue/2012/07/20/the-death-of-seo-the-rise-of-social-pr-and-real-content/

“Google is in the process of making the SEO industry obsolete, SEO will be dead in 2 years.”

Adam Torkildson, SEO consultant

Ken Krogue, Forbes.com

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 7

Comments and feedback

Linking to readers’ blogs

Community and collaborative documentation

Doc sprints

Social media

Rewards and gamification

Tools

WikiTwitterFlickrYouTube

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 8

What is a wiki? https://confluence.atlassian.com/display/DOC/

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 9

Thank you! Fixed.

Some readers’ comments are simple: typos, broken links, and such

Comments

Hi, link is broken

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 10

Some comments are full of hard-won and relevant information

This is BRILLIANT Thank you

Comments

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 11

People like to let us know they’re keen on a new feature

*Waits intently for Apache Connector 2.0 to be built on windows*

Comments

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 12

Yep, I see where you’re going with the “emotional experience” thing

Comments and fun

Demo

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 13

Types of comments received

Suggesting a feature 17.24%

Requesting support 10.34%%

Requesting help 31.03%% Unhelpful 3.45%

Addition or correction 6.9%

Supplying information 31.03%

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 14

Dealing with feedback

Replying quickly, with what you know

Being friendly, polite and “real”

Gaining confidence

Enjoying positive reactions

Handling angry responses

Black Cockatoos near my house

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 15

Don’t forget to ask: “How was it for you?”

{widget:url=http://atlassian.wufoo.com/forms/let-us-know-what-you-think-of-the-new-sdk/|height=800px}

Wufoo forms for gathering feedback

wufoo.com

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 16

Linking to readers’ blogs Engage bloggers

Plug a gap we cannot fill

Expand our own knowledge

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 17

Open editing of wiki pages Our vision

Is it safe?

Industry and environment

Authors

Monitoring by technical writers

RSS feeds

Wiki watches

You can all sleep sound tonightWe’re not crazy or anything

A team of technical writers

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 18

Permissions and ACLA

Comments – anyone can comment

Product documentation

All employees can update

Other contributors sign a licence agreement first

Atlassian Contributor License Agreement (ACLA)

Based on Apache Contributor License Agreement

Guards the rights of all

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 19

Comments – anyone can comment

Product documentation

All employees can update

Other contributors sign a licence agreement first

Atlassian Contributor License Agreement (ACLA)

Based on Apache Contributor License Agreement

Guards the rights of all

Any technical writers in the room?

A Powerful Owl in my neighbourhood

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 20

Creative Commons copyright licence

CC-by licence on all pages

Use our documentation in any way you like

Acknowledge us as the source

Contributors know where they stand too

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 21

Collaboration – release notes

Demo

https://confluence.atlassian.com/display/DOC/Confluence+4.3+Release+Notes

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 22

Collaboration – release notes page history

Demo

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 23

https://confluence.atlassian.com/display/DOC/Database+Setup+For+MySQL

Collaboration – database setup

Demo

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 24

Shut ‘em up in a room together

Don’t let ‘em out until the documents are written

Doc sprints

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 25

Given a focus, people do awesome stuff

Doc sprinters

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 26

The biggest sign of victory is how many pages I managed to delete!

Doc sprint results

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 27

Planning

Templates

Tutorials themselves

Retrospective

Fun stuff

Hall of fame

The wiki was central to the event

Doc sprint wiki

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 28

Incorporating social media – Flickr

{widget:url=http://www.flickr.com/photos/31065906@N08/sets/72157623503923898/}

Demo

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 29

Incorporating social media – videos

WordPress: “Add Media”

Confluence: “Widget macro”

Other: Embed HTML

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 30

Example of a video in a document

Demo

https://confluence.atlassian.com/display/DOC/Confluence+4.3+Release+Notes

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 31

Links are magic

Galahs on my street

Shareable

Currency of the Web

Doorway to your docs

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 32

A little bird told me

Twitter as a medium for release notes

Tips via Twitter

Rewarding the community

Gamification

How to embed Twitter

Rainbow Lorikeets on my eaves

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 33

Tweeting your release notes

Ooo-er, did I tweet that? Bite-sized chunks

Interactive

Shareable

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 34

Live Twitter stream embedded into the page

Tips via Twitter #ConfluenceTips

Demo

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 35

Rewards – badges for tip tweeters

Win-win, like most social tools

Community and identity

Recognition

Promotion

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 36

Gamification – the Dragon Slayer

Complex configuration guide

Enjoyment

Feedback

Rewards

Charlie’s clothing and armour

Getting the task done

Fun and camaraderie

T-shirt

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 37

Fun stuff is at top and bottom of page

Good solid, well-tested “how to” instructions in between

Dragon Slayer pages

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 38

Live Twitter stream on the page

Link to dragon slayers’ forum

Dragon Slayer interactivity

Invitation to tweet your status

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 39

People love a game

Dragon Slayer Twitter stream

Demo

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 40

How to embed Twitter into your page

http://twitter.com/home?status=My status

http://search.twitter.com/search?q=My query

A simple HTML link

A widget with a search

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 41

Twitter link and widget in Confluence

{widget:url=http://search.twitter.com/search?

q=AtlassianDragons}

[tweet your status|http://twitter.com/home?status=My status]

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 42

Building a Twitter widgethttps://twitter.com/settings/widgets/new/search

Demo

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 43

Which emotion would you rather have?

Or…

We have both

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 44

Confluence, Tech Comm, ChocolateA wiki as platform extraordinaire for technical communication

http://xmlpress.net/publications/chocolate

My book

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 45

References 1

Social media

“How to nurture an online community” by Rusty Williams on iMedia Connection: http://www.imediaconnection.com/content/17758.imc

“The Death Of SEO: The Rise of Social, PR, And Real Content” on Forbes.com in July 2012: http://www.forbes.com/sites/kenkrogue/2012/07/20/the-death-of-seo-the-rise-of-social-pr-and-real-content/

Confluence wiki

Confluence documentation: https://confluence.atlassian.com/display/DOC

Guide to developing technical documentation on Confluence: http://confluence.atlassian.com/display/DOC/Developing+Technical+Documentation+on+Confluence+Wiki

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 46

References 2

Feedback via comments and online forms

Wufoo Online Form Builder: http://wufoo.com/

Confluence documentation on using the Widget macro: http://confluence.atlassian.com/display/DOC/Widget+Macro

Comments can be fun: https://confluence.atlassian.com/display/DOC/Cheese+Macro

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 47

References 3

Linking to external blog posts

The “Tips of the Trade” page in the JIRA documentation: http://confluence.atlassian.com/display/JIRA/Tips+of+the+Trade

The “Tips of the Trade” page in the Confluence documentation: http://confluence.atlassian.com/display/DOC/Tips+of+the+Trade

Open editing of wiki pages

Creative Commons licence: http://creativecommons.org/licenses/by/2.5/au/

Atlassian Contributor License Agreement: https://confluence.atlassian.com/display/ALLDOC/ACLA+v2.0

Apache Contributor License Agreement: http://www.apache.org/licenses/icla.txt

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 48

References 4

Doc sprints

A study titled “Why do people write free documentation?” on O’Reilly ONLamp.com: http://onlamp.com/pub/a/onlamp/2007/06/14/why-do-people-write-free-documentation-results-of-a-survey.html?page=2#most_popular

The results of the doc sprints: http://ffeathers.wordpress.com/2010/03/07/we-held-a-doc-sprint-and-it-was-awesome/

http://ffeathers.wordpress.com/2010/11/07/every-doc-sprint-is-different/

How to plan a doc sprint:http://ffeathers.wordpress.com/2012/09/07/how-to-plan-a-doc-sprint/

Our doc sprint wiki: http://confluence.atlassian.com/display/DOCSPRINT

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 49

References 5

Embedding Flickr images into a documentation page

Flickr: http://www.flickr.com/

A page showing an embedded Flickr photo set – the doc sprint “Hall of Fame”: http://confluence.atlassian.com/display/DOCSPRINT/Doc+Sprint+Hall+of+Fame

Confluence documentation on using the Widget macro: http://confluence.atlassian.com/display/DOC/Widget+Macro

Embedding YouTube videos A page with a video – product release notes : https://

confluence.atlassian.com/display/DOC/Confluence+4.3+Release+Notes

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 50

References 6

Twitter

Twitter: http://twitter.com/

A guide to Twitter for technical communicators by technical communicators: https://wikitechcomm.onconfluence.com/display/DOC/Home

Introduction to Twitter with many useful comments from readers: http://ffeathers.wordpress.com/2009/06/08/twitter-as-a-medium-for-release-notes/

http://ffeathers.wordpress.com/2011/01/02/how-to-embed-twitter-streams-and-prepopulate-tweets-in-your-document/

The “Tips via Twitter” page for the JIRA documentation. http://confluence.atlassian.com/display/JIRA/Tips+via+Twitter

Building a Twitter widget: https://twitter.com/settings/widgets/new/search

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 51

References 7

Documentation as an emotional experience

The Dragon Slayer documentation: http://confluence.atlassian.com/display/ATLAS/Here+Be+Dragons

My post about the Dragon Slayer documentation: http://ffeathers.wordpress.com/2009/10/10/i-got-dragons-and-tweets-in-my-docs/

Bill Kerschbaum’s post about humour in documentation: http://wordindeed.wordpress.com/2010/02/25/did-you-hear-the-one-about-the-user-guide-with-a-sense-of-humor/

Ellis Pratt’s post on the Cherryleaf blog: http://www.cherryleaf.com/blog/2010/02/turning-technical-documentation-into-an-emotional-experience-for-the-customer/

Engaging readers, by Sarah Maddox – tweet @sarahmaddox 52

Contacting me

Email: sarah@atlassian.com

Twitter: @sarahmaddox

http://twitter.com/sarahmaddox

LinkedIn: http://au.linkedin.com/in/sarahmaddox

Blog: http://ffeathers.wordpress.com

Other blog: http://travellingworm.wordpress.com/

Let me know if you’ve done something similar, or something totally different

The end