Tag Archives: writing

Talking to Ellis Pratt about Conversation and Community

I spoke with Ellis Pratt with Cherryleaf in London from my home in Austin for a video interview last week, and the shortened version is available online now.


He had many good questions, ones that I enjoy discussing all the time, such as the future of our profession. One good one was “What will user documentation look like in the future?” Also, “Is there too much reliance on search?” and “What are the blind alleys?”

I’m not sure I have all the answers, but I do enjoy talking to people who “get” it like Ellis does.

Here’s a direct link to the interview, which has slides guiding you through highlights of the the questions and answers.

I really appreciated Ellis Pratt and Cherryleaf giving me the opportunity to talk about the concepts in my book. These types of interviews – video, audio, lunchtime, you name it! – lend more dimension to the book than just flat pages. I appreciate it!

Content strategy – so much to learn

I just ordered Kristina Halvorson’s (@halvorson on Twitter) book, Content Strategy for the Web after viewing “10 things every business person needs to know about content strategy” slideshare.net presentation (by Melissa Rach). Powerful stuff!10 things every business person should know about content strategy

View more presentations from mrsruble.

Reminds me that I need to get cracking on a presentation to supplement my book. I’ll finish up this blog post for now. 🙂

I learned a lot just by clicking through this slide deck so I am anticipating a good education from the book as well.

Content strategists seem to have interesting conversations around the #contentstrategy Twitter hashtags. I learned that PBS has a Chief Content Officer and apparently so does NPR.

I enjoyed the post with notes about content strategy on I’d Rather Be Writing, Three Questions To Start Thinking Like a Content Strategist. The link list at the end is very valuable. Another fascinating set of links for learning is on this Friday content strategy: installment 3 post. It has this excellent warning right up front: Caution: reading the following may make you passionate about content strategy and knowledgeable about recent content news.

So, consider yourself warned. Starting to read this post and clicking through to all the links may lead you through a most fascinating journey to learn more about content strategy.

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 scribd.com 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 WordPress.tv 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 Compete.com. 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.



What’s your favorite JustWriteClick post?

I like to keep an eye on what posts are popular, although with a blog, you can define popular in many different ways. Most comments, most views, or highest average daily views. So if you’re new to my blog, (and the recent uptick in subscribers might indicate that some of you are, so welcome!) you might enjoy these previous posts.

Here are the most popular posts based on total views (I think this is slightly inaccurate for the life of my blog but still interesting):

Here are the most popular posts based on average daily views:

Here are the most popular posts based on number of comments:

What are your favorites – the most discussed or the most widely read? Feel free to leave a comment.


Dangerous future for technical writing?

Photo courtesy of Hamed Saber, http://www.flickr.com/photos/hamed/

I finally got to watch the final season of The Wire and was fascinated with the interplay of the media in the plot lines that included journalists and editors at the Baltimore Sun. Over at the Duo Consulting blog, Diane Wieland wrote a great entry titled “Why Pay When You Can Get It For Free.” In it, she discusses the general freaking out of old media and their dated business models. Yes, people want news. Yes, people can get news for free. Previously the best way to get your news was through journalism and your daily newspaper – but the publishing systems have changed and allowed for citizen journalism and news updates through various channels.

I naturally draw a parallel between citizen journalism and user-generated content. After all, in software, technical writers are like the journalist is – finding the relevant story for a particular audience, interviewing to get the facts, presenting in a fair, nonjudgemental manner, and writing to a deadline. Must we be introduced to the new tech comm, like this lead in for the All things Digital article about the Washington Post admitting that the Huffington Post could take them to survival school?

“Old media, meet new media, meet old media’s new media.”

Will Google Wave be part of that new tech communicator’s arsenal? My fellow Agile writer Shannon Greywalker thinks so and describes its usefulness in this post, Google Wave changes everything you know about agile collaboration and technical documentation.

What FLOSS Manuals did at Winter Camp

My summary view is that we activated and energized our network, borrowing those terms from Zita Joyce, my outreach co-worker for the week whom I quizzed endlessly about what it’s like to live in Amsterdam. It was a productive and exciting week for a fledgling non-profit like FLOSS Manuals. We have a pile of work ahead of us, but by distributing the work to teams we have created efficiencies and people have chosen their areas of interest and abilities. Check out this diagram showing the work from the week.

Floss Diagram

View more documents from r00s.

There’s also a great video depicting “A day in the life of FLOSS manuals…”

“Roll Up! Roll Up! for the greatest show on earth. That’s right never before have you had such unlimited access to a distributed network
meeting in real life. This time we know it’s for real. This is pure gold for network academics the world over.” I’m just rebroadcasting from Mick Chesterman, an amazing activist and video pro with whom I asked about everything from screencasting to quilt blogs.Yet those two bits of media best barely describe my amazing week in Amsterdam. So I offer my photos from a couple of sightseeing tours as well.

And now, I’d better get to work on the Firefox Book Sprint! We have fourteen remote collaborators and starting in earnest tomorrow. If you’re in the Austin area, join me at Flightpath at Duval and 51st from 5:00-7:00 tomorrow and Wednesday (3/17 and 3/18). You’ll find me as the writer with the FLOSS Manuals sticker on my laptop.


Managing Writers book includes well-earned experience stories

Richard Hamilton’s new book, Managing Writers: A Real World Guide to Managing Technical Documentation, is clearly organized and a fast read. It often reads like a reference guide, a book you could keep on your bookshelf for years to come.

It is a reference guide in my view, because you can go straight to the table of contents and pick from the list of topics. Want to get your arms around people? Refer to many chapters on Managing People. Need to know insider information on projects before it spirals out of control? Stop the spin machine and go to the pages about Managing Projects. Wondering if the latest alphabet-based tossed salad of acronyms will actually solve your user’s information problems? Hightail it to the Managing Technology chapters. Each of his chapters offers the depth and detail you’d need when faced with a situation you hadn’t seen before. For example, if you’re new to Localization, the information offered will help you ask the right questions and help you get started while avoiding headaches and “time sinks.”

As I read through this book, I felt like I was having a nice long lunch with one of my favorite managers. It’s sprinkled with stories and phrases like “gold-plated Cadillac.” I enjoyed reading about his path to technical publications. It seems many people are eager to leave tech pubs once they start in it. Richard didn’t know much about tech pubs, and wondered if he was leaving the world of technology, but accepted a position anyway. He was willing to learn and stay with it. And stay with it he did, for many years beyond the first two he promised to the hiring manager.

Whether you’re already managing a handful of writers or just starting out, or if you’re hoping to move towards management in technical publications, I think you’ll find this book helpful. Even an experienced tech pubs manager will enjoy hearing another’s perspective and will find many familiar themes that match their own companies and product documentation.

Scott Abel had three copies of the book that he was giving away on Twitter last week – get one before they’re gone, or buy your own copy to read and then keep on your shelf. Like I said myself on Twitter when I first read the book, thank you Richard, for no cat herding references.