Social media in technical documentation – a presentation

Last week I attended Atlassian Summit 2010. This was a conference in San Francisco focusing on Atlassian products such as Confluence wiki, JIRA issue tracker and more. At Summit, I presented a session on using social media in technical documentation. We also got a bit emotional about the docs. 😉

This was pretty cool. It’s the first time I’ve given a talk at an Atlassian conference. I was totally stoked and very nervous. Apart from a technical glitch or two (basically, Twitter was borked and my presentation was supposed to use Twitter) all went well. The audience was great. Thank you guys!

Downloading the presentation and watching the video

If you like, you can watch the video of me doing the talk (yes, they filmed me!) or download the slides:

• Watch the video of me giving the presentation on the Atlassian Summit 2010 site. You’ll see two big picture boxes in the right-hand half of the screen. The top one is the video. The first 22 minutes are my part of the session. In the second half of the video, Jeremy Largman talks about using Confluence as a support knowledge base and the tools the support team have built to extend Confluence. His presentation is awesome and packed with information. Well worth a watch. If you’d like to bump up our ratings, click the “Like” button just above the video. Let me know what you think of it too. I’m quite pleased with the way it turned out. I was expecting far worse! I was quite nervous, and my mouth got very dry. They’ve done a really great job of compiling the video with me and the presentation slides in one single view.
• See the slides on Slideshare: Felt the earth move when I read your docs (Slideshare)
• Download the slides in PDF form (1,901 KB) from this blog post that you’re reading now: Felt the earth move when I read your docs (slides only)
• Download the slides with notes in PDF form (1,907 KB) from this blog post: Felt the earth move when I read your docs (slides with notes)

Summary of the presentation

My talk was called “Felt the earth move when I read your docs“. Actually, it was originally called “Felt the earth move when I read your docs, mate” but someone with a fair bit of influence 😉 suggested that I remove the word “mate” from the title. You may notice that the word sneaked into the presentation itself anyway! Here’s a still image that I grabbed from the video:

Social media in technical documentation - a presentation

It’s all about using social media to engage readers in the documentation. It’s also about fun and games and a bit of emotion in the docs. We looked at these tools:

• Confluence wiki
• Twitter
• Flickr
• Wufoo

And we saw how we can use them in technical documentation:

• Using comments and forms to get actionable feedback from readers and customers.
• Linking to external blogs from within the documentation.
• How you can set up and manage your documentation while allowing external people to edit it.
• Using Twitter as a medium for release notes.
• Encouraging customers and readers to tweet hints and tips, and publishing the Twitter stream in your documentation.
• Holding a doc sprint.

To round it off, we looked at the Atlassian Dragon Slayer documentation, which combines a game, social interaction and a laugh with good solid well-tested technical writing.

More

The Atlassian Summit presentation is related to one I gave at AODC recently. If you’re interested in a lot more detail about each of the topics covered here, then take a look at my earlier post: AODC 2010 day 2: Engaging your readers in the documentation.

Craig Smith snapped a cool picture of me giving the presentation. He also wrote some great summaries in his Atlassian Summit 2010 Day 1 Wrapup.  Thanks Craig!

At the end of my slides are a number of references and links that I hope you’ll find useful. They include links to blog posts by other technical writers who are experimenting with social media and other adventures in the docs.

The Atlassian web site has a lot more Summit presentations, including a number about Confluence and how people are using it.

Attending this conference was a great experience. I’m really lucky to have had the chance to be there and to meet all those great people. Thank you to all the attendees for the ideas you brought and the fun we had.

AODC Day 3: I can’t spell Ambliance!

Last month I attended AODC 2010, the Australasian Online Documentation and Content conference. We were in Darwin, in Australia’s “Top End”. Over the last couple of weeks, I’ve been posting my summaries of the conference sessions, derived from my notes taken during the presentations. All the credit goes to the presenter. Any mistakes or omissions are my own.

Frank “Choco” Munday presented the last session of the conference. Choco is an awesome presenter. It’s something of a tradition (the AODC has a few of those) that the conference ends with a raucous laugh. Choco excels at putting that sort of finishing touch to an event!

AODC Day 3: I can't spell Ambliance!

In this presentation, we looked at some horrors that technical writers may encounter and indeed should do our utmost to avoid.

Eggcorns

“Eggcorn” is a linguistic term for the practice of replacing a complex or scientific term with a more commonly-used word, especially when people swap the unfamiliar part of a phrase with a word that occurs more often in their own dialect. An oft-quoted example is the use of “old-timers disease” instead of “Alzheimer’s disease”. Wikipedia says that the term “eggcorn” was coined by Geoffrey Pullum in 2003, based on a case where a woman used the phrase “egg corns” when she meant “acorns”.

Choco was specifically concerned with “eggcorns” as spell-as-you-speak errors.  He took us through a rollicking and somewhat scathing look at a number of eggcorns, such as:

• “Should of” for “should have” – a frequent occurrence in Australia.
• “At your beckoned call”.
• “For all intensive purposes”.
• “I think I might be lack toast and tolerant” for “lactose intolerant”.

Choco showed a number of examples from print and online media, and lambasted them thoroughly. It’s well worth getting him to run through his list with you.

Mixed metaphors

Next Choco turned his eagle eye to mixed metaphors. Politicians were worth their weight in gold here.

Choco said, “I would slip one or two into my technical documentation, just to see what happens”. (Mixed metaphors, that is, not politicians.) 🙂

Unwords

Unwords got some Choco love too. Choco suggests we take a look at the Unword Dictionary at unwords.com.

So I did that. Here’s an unword I like:

19. bandpulliphobia (bănd-pu’lə-fō’bē-ə)

1. a. (n.) The fear of pulling off a band-aid; Especially when counting down from three.

Remembering that we were attending a serious technical writing conference, Choco did mention with a straight face (for a split second, anyway) that unwords are words that are not really words, so there’s a chance that people won’t understand them. We should therefore avoid them in our technical documentation. I was glad of this reminder, as I was starting to feel the temptation. 😉

My conclusion

A fittingly boisterous end to AODC. Fun, but with a serious undertone. Thank you Choco.

Collective noun for a group of technical writers

This week a colleague, Tom, came up to me with a big grin and asked, “What’s the collective noun for a group of technical writers?”

He had another developer in tow, a new starter at that, and the grin made me wonder what mischief lay behind the question. 😉 But it’s a goody and it made me laugh. I came up with “a scribble of technical writers“. Later, it occurred to me that we could call a group of agile technical writers a “jot“.

Can you think of any good names for us and for what happens when we get together in a group?

Doggerel fooding your release notes

Warning: Not for sensitive viewers. This post contains a truly awful pun, bad grammar and lamentable verse. Read on at your own peril. Are you sitting down?

Doggerel fooding your release notes

At work we write the release notes a while before each release and let our colleagues know when page is available for their edification and their delight. We let them know via a blog post on our internal wiki. Such blog posts tend to be a bit monotonous. “The Crowd 2.0.3 release notes are now available. Please note that this document is a draft and is for internal information only.”

This week I had a bit of fun. It was a spur of the moment thing that took me just two minutes. Hence the deplorable verse:

Rhyming the Crowd 2.0.3 Release Notes

Now you can see
What’s in Crowd 2.0.3
We’re not kiddin’
But the doc’s still hidden
So don’t give it away
But do have your say

Tom, one of our developers, snapped back with this comment:

“Doggerel fooding the release notes?”

LOL. Nerd humour at its best. Thanks Tom!

To “dogfood” is to use your own product, so that you experience its strengths and weaknesses intimately. The term started off as a noun phrase in “eating your own dog food” but is now commonly used as a verb too. In certain circles. 😉

Yard table assemblage instructions

These “Yard table assemblage instructions” were included with a garden table we bought. 🙂 Actually, the structure of the guide is good. There’s a list of parts and then the “how to”. It’s just the language that needs a bit of tender loving care. I love the way it degenerates towards the end, as if the poor author just gave up because it was too hard.

Assemblage parts:

1.One piece of iron flower pattern glass (in midst have a hole).

2.Four table feet.

3.Two fixed stators.

4.Eight screws.

5.Eight screw caps.

Assemblage method:

1.Use the screws and screw caps screw down the table feet and fixed stators.

2.Table top is upward.

3.half-round plastics of under the table top direct against the table feet, Then press it down.

We did manage to assemble the table with no trouble.