Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah...
Transcript of Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah...
![Page 1: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/1.jpg)
Slide 1Engaging your readers in the documentation – by Sarah Maddox Slide 1
AODC 2010
Engaging your readers in the documentation
13th Australasian Online Documentation and Content Conference12th – 14th May 2010, Darwin
![Page 2: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/2.jpg)
Slide 2Engaging your readers in the documentation – by Sarah Maddox Slide 2
AODC 2010 Introducing the topic
Proposal: Good documentation needs:
Excellence in the 5 Cs: Completeness, conciseness, clarity,
correctness, consistency, cohesion.
Another C: Collaboration
An emotional experience
In this presentation:
Engaging your readers in the documentation
Documentation as an emotional experience
Count „em
Huh?
![Page 3: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/3.jpg)
Slide 3Engaging your readers in the documentation – by Sarah Maddox Slide 3
AODC 2010 Introducing me
Sarah Maddox
Day job:
12 years as technical writer
10 years as software developer
Now in a team of 5 writers
Fun:
Rollerblading and RipStikking
Chocolate
![Page 4: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/4.jpg)
Slide 4Engaging your readers in the documentation – by Sarah Maddox Slide 4
AODC 2010 Why engage your customers?
The “social enterprise”
Why engage people at all?
Why engage people in the documentation?
Coming up:
Why
![Page 5: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/5.jpg)
Slide 5Engaging your readers in the documentation – by Sarah Maddox Slide 5
AODC 2010 Why engage people at all
Engaged customers
buy more
are more satisfied with the product
help each other
We gain valuable insight into our own product
We influence what people say and think about us
We reduce our own support and maintenance effort
“Social” is happening anyway
It‟s fun for all
![Page 6: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/6.jpg)
Slide 6Engaging your readers in the documentation – by Sarah Maddox Slide 6
AODC 2010 Why in the documentation
For technical writers:
Our product is the documentation
Let‟s review the previous slide with that in mind
It‟s a good way of helping people
It‟s fun and rewarding
For the organisation:
One way of engaging customers in the product
Face of the company
Documentation as point of contact
Our standing in the organisation
![Page 7: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/7.jpg)
Slide 7Engaging your readers in the documentation – by Sarah Maddox Slide 7
AODC 2010 Engaging your readers
Comments on documentation pages
Links to readers‟ blogs and articles
Open editing of wiki pages
Tweeting the release notes
Tips via Twitter
Doc sprint
Coming up:
Engage
your readers
![Page 8: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/8.jpg)
Slide 8Engaging your readers in the documentation – by Sarah Maddox Slide 8
AODC 2010 Comments
Some reader‟s comments
are simple – typos and such
“Hoi Sarah
No worries always happy
to contribute.”
![Page 9: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/9.jpg)
Slide 9Engaging your readers in the documentation – by Sarah Maddox Slide 9
AODC 2010 Comments
Some comments are full of hard-
won and relevant information,
which can be copied into the
documentation
“Hi Stefan
Thank you for this information.
We have included it in the page,
under the heading „International
Characters in Attachment File
Names‟.
Cheers - Sarah”
![Page 10: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/10.jpg)
Slide 10Engaging your readers in the documentation – by Sarah Maddox Slide 10
AODC 2010 Comments
“We‟re starting to
feel the LOVE
guys! If you need
any help on the
integration side,
don‟t hesitate to
contact me.”
Turning
disappointment
into LUV
Yep, I see where you‟re
going with the “emotional
experience” thing.
![Page 11: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/11.jpg)
Slide 11Engaging your readers in the documentation – by Sarah Maddox Slide 11
AODC 2010 Comments
“me too!
BTW – I have the
“because you‟ve
got issues” one,
the fabric is
superb….
hahaha”
Off topic but
totally engaged
“That‟s a pity, they
look kinda cool.”
![Page 12: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/12.jpg)
Slide 12Engaging your readers in the documentation – by Sarah Maddox Slide 12
AODC 2010 Comments
Readers are keen to help each other
People are social beings
Many comments are requests for help
We need to separate support and documentation
Comment culling is a necessity
What we‟ve
learned
![Page 13: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/13.jpg)
Slide 13Engaging your readers in the documentation – by Sarah Maddox Slide 13
AODC 2010
Disclaimer
Summarise and link to
an external blog post
Links to readers’ blogs
“Tips of the Trade”
is our title
![Page 14: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/14.jpg)
Slide 14Engaging your readers in the documentation – by Sarah Maddox Slide 14
AODC 2010 Links to readers’ blogs
Links to bloggers‟ “how to” articles
Research before adding the link
Disclaimer
Note on requirements for bloggers
Letting bloggers know about the tips page
Bloggers suggesting their posts by
Adding a comment
Editing the page!
![Page 15: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/15.jpg)
Slide 15Engaging your readers in the documentation – by Sarah Maddox Slide 15
AODC 2010 Links to readers’ blogs
People are keen to help each other
Bloggers like acknowledgement
Bloggers‟ content is high quality
This is a useful addition to the documentation
Plugs a gap we could not fill
Requires little maintenance
Engages the readers
Expands our own knowledge
What we‟ve
learned
![Page 16: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/16.jpg)
Slide 16Engaging your readers in the documentation – by Sarah Maddox Slide 16
AODC 2010 Open editing of wiki pages
Is it safe?
Industry and environment
Authors
Wiki permissions:
Developer documentation – any logged-in user
Product documentation – contributor licence (ACLA)
Comments – anyone
Creative Commons licence on all pages (CC-by)
Monitoring by technical writers
![Page 17: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/17.jpg)
Slide 17Engaging your readers in the documentation – by Sarah Maddox Slide 17
AODC 2010 Open editing of wiki pages
People are keen to help each other
Contributors‟ content is high quality
This is a useful addition to the documentation
Plugs a knowledge gap we cannot fill
Requires little maintenance
Engages the readers
Expands our own knowledge
Number of contributions is low but good
What we‟ve
learned
![Page 18: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/18.jpg)
Slide 18Engaging your readers in the documentation – by Sarah Maddox Slide 18
AODC 2010 Twitter
Max 140 characters
People really do
tweet about lunch
![Page 19: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/19.jpg)
Slide 19Engaging your readers in the documentation – by Sarah Maddox Slide 19
AODC 2010 Twitter
But that‟s
gobbledegook!
Conventions add
meaning, like
@, RT and #
![Page 20: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/20.jpg)
Slide 20Engaging your readers in the documentation – by Sarah Maddox Slide 20
AODC 2010 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
![Page 21: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/21.jpg)
Slide 21Engaging your readers in the documentation – by Sarah Maddox Slide 21
AODC 2010 Twitter as medium for release notes
People hijack your hash tag
Twitter on your phone
![Page 22: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/22.jpg)
Slide 22Engaging your readers in the documentation – by Sarah Maddox Slide 22
AODC 2010 Stats for shortened URLs
United States
Australia
France
Other
Germany
Other
![Page 23: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/23.jpg)
Slide 23Engaging your readers in the documentation – by Sarah Maddox Slide 23
AODC 2010 Twitter
Initial reluctance converted to enthusiasm
Work with marketing
Stick to your guns
A good tweet takes time to write
Tweet-a-choc sessions
Timing of tweets
Tweets disappear
What we‟ve
learned
![Page 24: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/24.jpg)
Slide 24Engaging your readers in the documentation – by Sarah Maddox Slide 24
AODC 2010 Tips via Twitter
Live stream from Twitter embedded
into the documentation page and
showing recent tweets
Encourage people
to tweet
Disclaimer
![Page 25: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/25.jpg)
Slide 25Engaging your readers in the documentation – by Sarah Maddox Slide 25
AODC 2010 Tips via Twitter
Quick guide with
auto-tweeting link
Complete
instructions for
noobs
Sounds like fun. How
do I tweet a tip?
The # tag is the key
![Page 26: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/26.jpg)
Slide 26Engaging your readers in the documentation – by Sarah Maddox Slide 26
AODC 2010 Tips via Twitter
http://twitter.com/home?status=My status
http://twitter.com/home?status=My+tip+%23ConfluenceTips
<a href=”http://twitter.com/home?status=Hallo World”>Say
hallo to the twittersphere</a>.
Cool. How do I create
an auto-tweeting link?
![Page 27: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/27.jpg)
Slide 27Engaging your readers in the documentation – by Sarah Maddox Slide 27
AODC 2010 Doc sprint
Shut „em up in a room together
Don‟t let „em out until the documents are written
![Page 28: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/28.jpg)
Slide 28Engaging your readers in the documentation – by Sarah Maddox Slide 28
AODC 2010 Doc sprintersGiven a focus, people
do awesome stuff
![Page 29: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/29.jpg)
Slide 29Engaging your readers in the documentation – by Sarah Maddox Slide 29
AODC 2010 Doc sprint results
The biggest sign of victory
is how many pages
I managed to delete!
![Page 30: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/30.jpg)
Slide 30Engaging your readers in the documentation – by Sarah Maddox Slide 30
AODC 2010 Doc sprint planning
When to start
Wish list
Communication plan
Invitations
Templates and style guide
Online tools
Budget, catering, venue, seating, network hubs…
Presentations – show and tell
Retrospective
Sarah‟s top tip: Get other
people involved early
![Page 31: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/31.jpg)
Slide 31Engaging your readers in the documentation – by Sarah Maddox Slide 31
AODC 2010 Doc sprint online
A group on Google Groups
Online chat room via Google Talk
Webinars
Wiki
![Page 32: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/32.jpg)
Slide 32Engaging your readers in the documentation – by Sarah Maddox Slide 32
AODC 2010 Doc sprint wiki
Planning
Templates
Tutorials themselves
Retrospective
Fun stuff
Photos
On the page
Live from Flickr
The wiki was
awesome
![Page 33: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/33.jpg)
Slide 33Engaging your readers in the documentation – by Sarah Maddox Slide 33
AODC 2010 Flickr and other photos
{widget:url=http://www.flickr.com/photos/31065906@N08/sets/72157623503923898/}
![Page 34: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/34.jpg)
Slide 34Engaging your readers in the documentation – by Sarah Maddox Slide 34
AODC 2010 Doc sprint fun
Theme
Chocolate middle names
Ed "Jaffa" Dawson
Rich "90% Cocoa" Wallace
Ben "Smarties" Speakmon
Mark "m&m" Halvorson
Online chocolate haiku competition
Know your Chocolate crossword
Chocolate blind taste test
Brown and then sticky
But the answer is not "stick"
It is chocolate.
![Page 35: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/35.jpg)
Slide 35Engaging your readers in the documentation – by Sarah Maddox Slide 35
AODC 2010 Doc sprint
What‟s brown and sticky? A stick
Readers are keen to help each other
People are social beings
Quality of output is very high
Retrospective is useful
Technical review after sprint
No chocolate in US Smarties
Will we do it again? Yes!
What we‟ve
learned
![Page 36: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/36.jpg)
Slide 36Engaging your readers in the documentation – by Sarah Maddox Slide 36
AODC 2010 Emotional experience
Documentation as an emotional experience
Dragon‟s Lair
Twitter integration in the documentation
Getting readers‟ feedback
Coming up:
Captivate
your readers
![Page 37: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/37.jpg)
Slide 37Engaging your readers in the documentation – by Sarah Maddox Slide 37
AODC 2010 Emotional experience
"Documentation as an emotional experience”
This @$$#*! documentation SUCKS!
Weird?
OK. Let‟s go for laughter,
pleasure, satisfaction
But wait...
![Page 38: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/38.jpg)
Slide 38Engaging your readers in the documentation – by Sarah Maddox Slide 38
AODC 2010 Emotional experience
"Documentation as an emotional experience”
Weird?
But wait...
I felt the earth move
when I read your docs, mate
OK. Let‟s go for laughter,
pleasure, satisfaction
![Page 39: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/39.jpg)
Slide 39Engaging your readers in the documentation – by Sarah Maddox Slide 39
AODC 2010 Dragon’s Lair – the problem
Cool integrated development suite
Complex installation and configuration
Emerging technologies
4 purposes of Dragon‟s Lair:
Demo the cool integration possibilities
Lead customers through the procedures
Document the steps and pain points
Track the improvements
![Page 40: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/40.jpg)
Slide 40Engaging your readers in the documentation – by Sarah Maddox Slide 40
AODC 2010 Dragon’s Lair – the game
8 stages, each with many steps
Rewards:
Charlie‟s clothing and armour
Fun and camaraderie with Atlassian and other dragon slayers
Getting the complex task done
Sense of achievement
T-shirt, fun
![Page 41: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/41.jpg)
Slide 41Engaging your readers in the documentation – by Sarah Maddox Slide 41
AODC 2010 Dragon’s Lair pages
Beware, all ye who enter, for here be dragons
![Page 42: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/42.jpg)
Slide 42Engaging your readers in the documentation – by Sarah Maddox Slide 42
AODC 2010 Dragon’s Lair pages
Fun stuff is at top
and bottom of page
Good solid, well-tested
“how to” instructions
in between
![Page 43: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/43.jpg)
Slide 43Engaging your readers in the documentation – by Sarah Maddox Slide 43
AODC 2010 Dragon’s Lair interactivity
Live Twitter stream
embedded on the page
{widget:url=http://search.twitter.com/search?q=AtlassianDragons}
[tweet your status|http://twitter.com/home?status=Funky status goes here]
Link to
dragon slayers‟ forum
![Page 44: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/44.jpg)
Slide 44Engaging your readers in the documentation – by Sarah Maddox Slide 44
AODC 2010 Dragon’s Lair Twitter stream
People love a game.
![Page 45: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/45.jpg)
Slide 45Engaging your readers in the documentation – by Sarah Maddox Slide 45
AODC 2010 Dragon’s Lair tweet
![Page 46: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/46.jpg)
Slide 46Engaging your readers in the documentation – by Sarah Maddox Slide 46
AODC 2010 Dragon’s Lair T-shirts
How often is documentation
cool enough to warrant a T-shirt?
![Page 47: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/47.jpg)
Slide 47Engaging your readers in the documentation – by Sarah Maddox Slide 47
AODC 2010 Emotional experience
People
Balance between fun and facts
Feedback on the Dragon‟s Lair documents
As of end March: 217 certified dragon slayers
Overwhelmingly positive
Helpful comments e.g. please explain content of XML file
Some vociferous complaints about the procedure itself
What we‟ve
learned
![Page 48: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/48.jpg)
Slide 48Engaging your readers in the documentation – by Sarah Maddox Slide 48
AODC 2010 Asking for feedbackDon‟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}
![Page 49: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/49.jpg)
Slide 49Engaging your readers in the documentation – by Sarah Maddox Slide 49
AODC 2010 A technical writer’s career
Learning and enjoyment
The “social enterprise” – jump in now
Make ourselves heard:
Suggest innovative ways to engage readers
Promote the use of technical writers at company‟s own conferences
Promote other ways for technical writers to meet customers
Write blog posts, on personal and company blog
Take active part in other social tools used by the company
![Page 50: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/50.jpg)
Slide 50Engaging your readers in the documentation – by Sarah Maddox Slide 50
AODC 2010 Recap
Comments on documentation pages
Links to readers‟ blogs and articles
Open editing of wiki pages
Tweeting the release notes
Tips via Twitter
Doc sprint
Dragon‟s Lair
Game
Interactivity via Twitter integration
Fun, community and good solid “how to”
Readers‟ feedback
What we‟ve
covered
![Page 51: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/51.jpg)
Slide 51Engaging your readers in the documentation – by Sarah Maddox Slide 51
AODC 2010 Bye
The end(References…)
![Page 52: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/52.jpg)
Slide 52Engaging your readers in the documentation – by Sarah Maddox Slide 52
AODC 2010 Contacting me
Blog: http://ffeathers.wordpress.com
Twitter: @sarahmaddox
http://twitter.com/sarahmaddox
LinkedIn: http://au.linkedin.com/in/sarahmaddox
Email: [email protected]
Other blog: http://travellingworm.wordpress.com/
![Page 53: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/53.jpg)
Slide 53Engaging your readers in the documentation – by Sarah Maddox Slide 53
AODC 2010 References 1
Social media
“How to nurture an online community” by Rusty Williams on iMedia Connection: http://www.imediaconnection.com/content/17758.imc
“How Intuit Makes a Social Network Pay” by Reena Jana on BusinessWeek: http://www.businessweek.com/magazine/content/09_28/b4139066365300.htm
“Social Business (also known as Enterprise 2.0)” by Peg Mulligan: http://pegmulligan.com/2010/02/09/social-business-also-known-as-enterprise-2-0/
Matthew Ellison consulting: http://www.ellisonconsulting.com/
My blog post about Matthew Ellison‟s talk at AODC 2009: http://ffeathers.wordpress.com/2009/05/20/aodc-day-1-feedback-and-collaboration-in-help/
![Page 54: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/54.jpg)
Slide 54Engaging your readers in the documentation – by Sarah Maddox Slide 54
AODC 2010 References 2
Social media (more)
Blog by Gordon McLean about the ISTC‟s special supplement on
social media: http://www.onemanwrites.co.uk/2010/03/21/role-of-
social-media/
Blog by David Farbey about the ISTC‟s special supplement on social
media : http://www.farbey.co.uk/index.php/2010/03/social-media-in-
technical-communication/
“The 90-9-1 Rule in Reality” by Mike Wu on Lithosphere blog:
http://lithosphere.lithium.com/t5/Building-Community-the-
Platform/The-90-9-1-Rule-in-Reality/ba-p/5463
![Page 55: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/55.jpg)
Slide 55Engaging your readers in the documentation – by Sarah Maddox Slide 55
AODC 2010 References 3
Tips of the Trade
The “Tips of the Trade” page in the Crowd documentation:
http://confluence.atlassian.com/display/CROWD/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:
http://confluence.atlassian.com/display/ALLDOC/Atlassian+Contribut
or+License+Agreement
![Page 56: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/56.jpg)
Slide 56Engaging your readers in the documentation – by Sarah Maddox Slide 56
AODC 2010 References 4
My blog post on ffeathers, 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/
Anne Gentle‟s article on twitip: http://www.twitip.com/focus-on-twitter-
for-technical-documentation/
Anne Gentle‟s book, Conversation and Community: The Social Web
for Documentation: http://xmlpress.net/publications/conversation-
community/
Our “Tips via Twitter” page for the Confluence documentation.
DRAFT at time of writing this presentation:
http://confluence.atlassian.com/display/DOC/Tips+via+Twitter
![Page 57: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/57.jpg)
Slide 57Engaging your readers in the documentation – by Sarah Maddox Slide 57
AODC 2010 References 5
Twitter (more)
Twitter‟s note about the limitations of the search:
http://apiwiki.twitter.com/Things-Every-Developer-Should-
Know#6Therearepaginationlimits
10 Ways to Archive your Tweets, by Sarah Perez on ReadWriteWeb:
http://www.readwriteweb.com/archives/10_ways_to_archive_your_tw
eets.php
A site that will URL-encode your text for you:
http://www.albionresearch.com/misc/urlencode.php
Twitter: http://twitter.com/
![Page 58: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/58.jpg)
Slide 58Engaging your readers in the documentation – by Sarah Maddox Slide 58
AODC 2010 References 6
Doc sprint
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
My post on ffeathers about the results of the doc sprint:
http://ffeathers.wordpress.com/2010/03/07/we-held-a-doc-sprint-and-
it-was-awesome/
My post on planning a doc sprint:
http://ffeathers.wordpress.com/2010/03/13/planning-a-doc-sprint/
We used a Confluence wiki. Here‟s the Doc Sprint wiki:
http://confluence.atlassian.com/display/DOCSPRINT
![Page 59: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/59.jpg)
Slide 59Engaging your readers in the documentation – by Sarah Maddox Slide 59
AODC 2010 References 7
Doc sprint (more)
Google Groups: http://groups.google.com/
Our online chat room was Tea Party: http://tea-party.appspot.com/
Google Talk: http://www.google.com/talk/
Webinars hosted by GoToMeeting: http://www.gotomeeting.com/fec/
Anne Gentle‟s book, Conversation and Community: The Social Web
for Documentation: http://xmlpress.net/publications/conversation-
community/
Book Sprint Central: http://www.booksprint.info/
The book about book sprints on FLOSS Manuals:
http://en.flossmanuals.net/booksprints
![Page 60: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/60.jpg)
Slide 60Engaging your readers in the documentation – by Sarah Maddox Slide 60
AODC 2010 References 8
Doc sprint (more)
Google‟s report of the Ogg Theora Book Sprint: http://google-opensource.blogspot.com/2009/09/ogg-theora-book-sprint.html
Andy Oram on the Challenges from a book sprint: the great things about ignorance and disorder: http://broadcast.oreilly.com/2009/03/challenges-from-a-book-sprint.html
squeakland‟s report of their first book sprint, to write an the Etoys Reference Manual: http://squeakland.immuexa.com/news/blog/archive/000903.jsp
Julie Stickler blogging on HeraTech about Agile Doc Reviews – The Documentation Sprint: http://heratech.wordpress.com/2009/12/04/agile-doc-reviews-the-documentation-sprint/
![Page 61: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/61.jpg)
Slide 61Engaging your readers in the documentation – by Sarah Maddox Slide 61
AODC 2010 References 9
Documentation as an emotional experience
The Dragon‟s Lair documentation:
http://confluence.atlassian.com/display/ATLAS/Here+Be+Dragons
Lisa Dyer‟s blog post about “Business intelligence, intelligent content
and devices, games, and noise”:
http://development.lombardi.com/?p=1191
My blog post about the Dragon‟s Lair documentation:
http://ffeathers.wordpress.com/2009/10/10/i-got-dragons-and-tweets-
in-my-docs/
Bill Kerschbaum‟s blog 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/
![Page 62: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/62.jpg)
Slide 62Engaging your readers in the documentation – by Sarah Maddox Slide 62
AODC 2010 References 10
Documentation as an emotional experience
Ellis Pratt‟s blog post on the Cherryleaf blog. “Turning technical documentation into an emotional experience (for the customer)”: http://www.cherryleaf.com/blog/2010/02/turning-technical-documentation-into-an-emotional-experience-for-the-customer/
Asking for feedback via a Wufoo form and Widget macro
Wufoo Online Form Builder web site: http://wufoo.com/
Confluence documentation on using the Widget macro: http://confluence.atlassian.com/display/DOC/Widget+Macro
An example of a Wufoo form built into a documentation page – see the documentation on the plugin development kit: http://confluence.atlassian.com/display/DEVNET/How+to+Build+an+Atlassian+Plugin
![Page 63: Engaging your readers in the documentation...Engaging your readers in the documentation –by Sarah Maddox Slide Slide 6 6 AODC 2010 Why in the documentation For technical writers:](https://reader036.fdocuments.us/reader036/viewer/2022062508/6012c54448067446d905101f/html5/thumbnails/63.jpg)
Slide 63Engaging your readers in the documentation – by Sarah Maddox Slide 63
AODC 2010 References 11
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+Hal
l+of+Fame
Confluence documentation on using the Widget macro:
http://confluence.atlassian.com/display/DOC/Widget+Macro
The end(Really)