Monthly Archives: July 2009

Announcing Conversation and Community: The Social Web for Documentation!

I’m so pleased to tell you that my book is available now from and and for sale in Austin, Texas at BookWoman on North Lamar. Published by XML Press, this book was fun to write, difficult to finish, and a dream come true for me, a kid who read 500 books in a school year in the second grade. I love books and I love this book especially. But I do want to keep improving it with blog entries here and responses to honest and thorough reviews, even negative ones.

This sample chapter is available (by direct PDF download or on Scribd) to start the conversation and I invite you to comment here or on Scribd.
Free Chapter Conversation and Community

If you’re here in Austin, I’m working on scheduling some book signings at local bookstores, and be on the lookout for an invitation to a book release party in the next few months! I want to share my excitement.

And lastly, I have to thank my blog readers – you are collectively loyal, smart, funny, and engaging. I couldn’t have written this book without you.

Twitter Guidelines from UK Government

According to this article in the Guardian, there’s a 5,000-word publication with the UK government’s guide to using Twitter. It’s available on even, according to this Digital Engagement blog entry.

I think there are good lessons to be learned here that are relevant to any technical communicator’s use of Twitter to communicate with customers, users, or the audience we write manuals to.

At the STC Summit in May 2009, I attended Phylise Banner’s session about social media tools used in education, Learn what the Academics Already Know. Naturally, Twitter came up, and a writer who works for the CDC here in the U.S. pulled up their Twitter page. They had 9,000 followers. Yes, 9,000. My jaw dropped. Now, just two months later, they’ve passed the 10,000 follower number on the CDC_eHealth Twitter account. If sheer numbers are an indicator, these microblog posts and status updates are here to stay, and part of many communication department’s overall strategy for talking with real people.

The guidelines are summarized in the Guardian article, which I’ll excerpt here since they’re so well written.

Human: He warns that Twitter users can be hostile to the “over-use of automation” – such as RSS feeds – and to the regurgitation of press release headlines: “While corporate in message, the tone of our Twitter channel must therefore be informal spoken English, human-edited and for the most part written/paraphrased for the channel.”

Frequent: a minimum of two and maximum of 10 tweets per working day, with a minimum gap of 30 minutes between tweets to avoid flooding followers’ Twitter streams. (Not counting @replies or live coverage of a crisis/event.) Downing Street spends 20 minutes on its Twitter stream with two-three tweets a day plus a few replies, five-six tweets a day in total.

Timely: in keeping with the “zeitgeist” feel of Twitter, official tweets should be about issues of relevance today or events coming soon.

Credible: while tweets may occasionally be “fun”, their relationship to departmental objectives must be defensible.

I found all four of these guidelines matched my own experience with Twitter in the two years I’ve been using it personally. But as I look for ways to use it for my employer to connect to customers about the iMIS product and our documentation offerings, I have to pause a bit especially on the first one: Human and not over-using RSS feeds to automate tweets. I think that constant automation of tweets without an overall conversation and reaction strategy is a poor idea, but I do think that tips, release notes features like Confluence technical writer Sarah Maddox (Twitter as a medium for release notes) and others are experimenting with, have a place. I guess the key to execution here is to write microposts that sound like a real person talking about the feature and pointing to the release notes naturally. If you do decide to automate somewhat, be on the ready for replies, and ensure the timing is right and the frequency of tweets doesn’t exceed what your followers would expect.

The frequency of tweets matches the guidelines set by The Twitter Book (which I loved), at around two to four a day. In the case of people who would follow a technical writer or a software company’s account to find out tips for using the software, I would think a few tweets a week may be sufficient. I think that frequency and the timing of the Twitter posts go hand in hand. I’m contemplating Tweeting about a software release that went out a few months ago, though, so I should probably think again about that idea.

And finally, credibility is crucial for success when technical writers consider Tweeting. If the perception is that you’re tweeting in short bursts rather that delivering a technical manual or training video, well, then you’ve lost some credibility. Be sure that your goals with Twitter are in line with your goals as a technical communicator.

What do you think? Are these government guidelines transferrable to the technical communication world? Or are constituents different enough from software users that we’d better find somewhere else from which to draw guidelines?

Popularity of writing the manuals?

Recently we had a few discussions on the FLOSS Manuals list about how to increase the quality of documentation for an open source project, and noted that quantity does not always increase quality. And someone noted that bad doc is worse than no doc at all! Naturally, I found parallels between the open source documentation world and the world of enterprise software.

Andy Oram started the discussion by sharing an essay positing that documentation will always be a cost, asking “Why is it more of a struggle for a project to provide information than to provide software?”  He asserts that any attempt to be comprehensive with documentation only results in overwhelming the budget, especially when video and in-person training are involved. I was reminded of Michael Hughes’ UX Matters post, Surviving Tough Times as a User Assistance Writer. He says, “We need to write less, and we need to write better stuff.”

Now, one counter question to Andy’s theory about bridging the training gap is this fact: training and education do not always come from manuals. So, in the case of an open source project’s documentation, does FLOSS Manuals align itself with the “support” mechanism of running software, or the “marketing/attention” mechanisms of getting software to be used?

In one case of a FLOSS Manuals user, Bill, he said he never can get people to read the documentation. He always ends up supporting people one-on-one with real-time communications. It sounds like Bill is the support department for his open source software project. Yet he could free up his own time by having killer doc that supports his users. I don’t think education necessarily aligns with “support,” though. Just because your users know how to use the software doesn’t mean they won’t run into the occasional bug or get stuck on a problem they can’t solve by themselves.

Here’s an example – I was talking to a guy who runs a WordPress consulting business with probably a dozen clients. He LOVES because if a client has a problem, he points them directly to a link with a video that tells them what to do to solve their problem. He’s still the central support mechanism though. The difference is that he didn’t have to create the content that helps his clients.

I think that with the introduction of community and earlier feedback in our documentation, doc becomes more “fun” and rewarding. I have much more fun writing entries for my blog than I do for the everyday doc that I write for my day job. Part of the “fun” is that the blog gives me more feedback – comments from readers, and blog stats I can see every day that show me that people really are reading what I write, plus I can see what they searched for.

What is converging is the idea that all these sources of documentation – lists, FAQs, tutorials, wikis, and so on – could live in and be maintained by one “community” or even a single hired hand. I say it in my book, and I’ll say it again, we are living in an amazing time where the audience and user is more accessible than ever through these tools that amplify conversations and connections.

Elsewhere on the web…

I have neglected to excerpt and link to some of my posts from the Duo Consulting blog. I’ve taken a break from writing for them for a few months while finalizing my book, but looking back at these posts, I wanted to share them with my readers! So here goes.

It Ain’t All Business: Using Social Networks for Good

When the social media groundswell turns altruistic, the results can be amazing. Here are two examples of both large and small differences made with a few simple connections. Connections made all the more quickly and with a higher rate of trust with the use of social media tools like social networks and Twitter.

Wanted: Good Home for Good Dog

Photo credit: Jim Sneddon on Flickr found using Flickr-Storm. More…

Web Content Mistakes and Worst Social Media Campaigns

We’re becoming more accustomed to correcting small-ish errors on wiki web pages when we come across them. I catch myself looking for an “Edit” link on other people’s pages, but of course not all web pages are editable. But that habitual reaction has me wondering about web content mistakes and how best to correct them.

What’s the biggest web content mistake you’ve seen (or done?)

Michael Silverman told us about the six-year-old news article that went out due to inaccurate automation techniques, causing a 75% drop in a company’s stock price before it could be corrected, in Save $1 Billion with Web Content Management! Now that is a big web content mistake. More…

Terms of Contention: Who Owns Uploaded Content?

Terms of use and privacy policies, how often do you read these terms before agreeing to them? Most of us would admit we don’t read the fine print even when it’s prominent large type. But when a community member does pay attention to a change in the terms of service and gets 100,000 other people to pay attention also, you’d better believe that the originator of the terms and policies are going to take notice. That scenario happened just last week for members of Facebook, one of the largest social media sites with 175 million active users and the most visited site in January 2009 with 1.2 billion visits according to More…

How my 5-year-old sees web content

I had the funniest inquiry from my five-year-old son today. He said, “Mom, how does the computer know there are new Lego sets?”

Now, I didn’t launch into a description of Document Engineering: Analyzing and Designing Documents for Business Informatics and Web Services even though Bob Glushko’s book is on our bookshelf. I had to stop and think before answering, and I realized his view of the web is quite retail- and consumer-oriented. He uses a computer for web browsing (using the Glubble Firefox Plugin), playing games, and that’s about it. He’s still piecing together how the pictures, videos, and text about Legos gets onto his computer, and he’s building his own ideas about how it all works. Fascinating!

My answer was a simple “Lego is a company, and when they make a new set, they put the information on the web site, and then you go look at it.” I don’t think there’s much more to it, from a five-year-old’s view point.

The Lego site has such great marketing – they know their audience members are the kids, but they still know the targets are the parents with the purchasing power. Their designers have a great set of videos that describe the toys and sets to kids. Check them out.

Maybe I’m looking too far ahead at career choices for my kid, but I’d be proud to raise either a Lego Designer or a Document Engineer.


Biggest der! moments

Huh or Duh or Der, but not Aha. The Aha moment is reserved for that moment of discovery and understanding. The Der moment is when you realize you’ve done something quite silly!

My recent one was during my final weekend with my book files, the weekend of July 4th. Friday was the Independence Day holiday, so I hung out with my husband while the kids were at day care, we saw Transformers, and then I spent about four hours with my book. I took my son to swimming lessons, where they have wifi (this is Austin, baby!) and continued final proofing and so on, getting it ready to send to the designer for his final touch.

When we got back from swimming lessons, I uploaded the zip file so the designer could get to it. Saturday morning, I had a mild heart attack when I thought I had lost all my changes I worked on Friday, when the zip file was returned from the designer with none of my text changes or two index additions. Yikes! I had to wake my system admin husband up and everything. 🙂 He found the files – my searches came up with nada, nothing.

Come to find out, I had stupidly been working in a “Downloads” folder instead of in my usual work area, after downloading the file from the designer in a previous handoff. And neither Microsoft’s Desktop search nor Google’s Desktop search was configured to find files in the Downloads folder, because it was marked “hidden,” isn’t that annoying? (Here’s more info from Google on how to fix that problem.) But my hero husband came to the rescue, whew.

What’s your biggest “der” moment lately? On Twitter, @dmnguys say “Too many of those moments to list…” 🙂 How about you?

Creative Commons is so cool

The two photos on my book cover are licensed with the Share-Alike and Attribution Creative Commons license, which means that as long as the book cover created with those photos is also shared for others to adapt, we can use the photos by attributing the source of the photo – and the photographer.

Last night I used FlickrMail to send messages to both of the photographers to tell them we’re using their photos, and also to get their mailing addresses so we can send them a printed copy of the book.

And then the neatest thing happened. From the photographer of the Danish keyboard I received a message in return already, and a request to be his friend on Facebook. I accepted and checked out his online profile. As it turns out, he’s in Houston and I’m in Austin!


He had already posted a shot of the cover to his Wall, and his friends were commenting and complimenting his photography. I got so excited I broke my cardinal rule of never posting to social sites during work hours, and I added my own gratitude and compliments. I think it’s the neatest thing that Creative Commons sharing gave us both such a boost.

As Jude said in his FlickrMail reply, “I enjoy sharing my work with the community. I’m so glad you found it. I think the Creative Commons License is such a wonderful resource.”