Monthly Archives: June 2009


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.

Conversational robots

Photo courtesy a voir etc...

Move over qmail mailer-daemon*, Little MOO from is my new favorite polite responder. Check out the auto-response I received after asking their support team a question using their webform. New favorite polite robot responder:

“Remember, I’m just a bit of software, so please don’t reply to this email. You’ll find our Service Agents far more conversational.”

Plain awesome. But obviously written by a human, unlike this robot chat program that won a prize last year for being most likely to fool people into thinking it was a human. The transcript of the robot’s “interview” is entertaining reading. They programmed it to be sarcastic and entertaining, which comes across as plain cheeky sometimes. Talk to him yourself at

*In case you’re curious, the previous robot response winner for me is,

“Hi. This is the qmail-send program at
I’m afraid I wasn’t able to deliver your message to the
following addresses. This is a permanent error; I’ve given up.
Sorry it didn’t work out.”

Does anyone else have favorite automatic responses that you’ve written or received? Please do share.

Does designing content for scanning devalue the content?

I just read a great post by Rajesh Setty on the Lateral Action blog called 9 Ways People Respond to Your Content Online. Maybe it’s because I’m in the final countdown before my book is permanently affixed to the pulp of dead trees, or maybe it’s because I’m looking at online user assistance tools to see how they can enable conversational documentation, but it struck me that user assistance gets stuck in that first low value category often. Here’s the excellent visual that shows how return on investment increases as the response to the content becomes more and more spreadable, actionable, returnable, and impossible to ignore.

9 ways people respond
Image courtesy Rajesh Setty

We are told as writers to make our online help scannable, that people don’t linger on it, they just want to find the answer, get in, get out, get on with their work. With the classic online help tools available, we rarely break into that second tier where readers can stop, save (as in social bookmarking), and shift their thinking based on the content.

And the final tier, send, spread, and subscribe, are actions not yet available in a classic help authoring tool. The “send” action can be via email only, and most help systems have to have that type of link specially coded. Spreading a link via social networks is not yet enabled in online help systems that I know of. And how many help vendors offer a subscribe or notification system?

If these response mechanisms are what your audience requires, you may have rethink your Help Authoring Tool selection and look at comment tools, blogs and wikis, and create a help system offers the features that give opportunity to leverage content and engage the readers. I believe Adobe has accomplished these goals with a hybrid approach that offers traditional online user assistance that includes the ability to “talk back” to the help writer via comments on each help topic.

I benefited from their approach this weekend in fact. I have a lot of footnotes in my book that point to relevant web pages and blog entries. I wanted to collect them into endnotes for the entire book. So I searched in the Indesign Support Center site. You can either search their Community Help or search the Indesign Online Help. The Community Help feature is in public beta according to the About page, and they are using a Google Custom Search Engine to “selectively index only the most high quality sites and resources.” I found a series of comments on the topic about footnotes that led me to a blog entry from the lead writer on His blog entry describes gathering footnotes into endnotes that use cross-references – apparently an old FrameMaker trick! And, to make it even more clear that a community helped this writer, he credits a forum post comment in a InDesign user forum with giving him the answer. Plus, after the blog post was published, another community member commented on the blog entry, giving him a link to the scripts that would automate the footnote to endnote process described in the blog entry. I was utterly blown away. Community documentation at work for me.

What do you think? Are the tools that cater to the needs of technical publications crowd already available? Or are technical writers going to move content to blogs and wikis due to feature demands from their readers?

Webinar available now from Scriptorium Publishing

I gave a webinar this week for Scriptorium that will be available online titled “Documentation as Conversation.” The fact that it’s recorded lets you avoid scurrying around rearranging meetings in Outlook just to attend it. It sold out which was great to hear, but I like that the message and conversation continues through the recording. One of my fun examples was the Wordle visualization of my tags from the social bookmarking tool,


During the question and answer session, someone mentioned they felt like social media made her feel like we’re becoming paleontologists. I think she referred to my many examples of how to “stalk” your users to learn more about them and their goals, especially if you document software. I search for my product’s name in job listings as well as look for job titles with my product’s name in LinkedIn to learn more about the people I’m writing for. I wrote up the technique in this blog post, Find your user’s vocabulary and use his or her key terms as keywords.

I also had a follow up email saying that people want to know, where should my team start conversations? Or where should we focus our time if we do start? In my book, I talk about phases: Listen, Participate, Share, Build a Platform. I think you should start with listening and monitoring what’s already being said. Next, start by commenting on blogs or by blogging yourself. A baby step towards blogging is to blog on an internal site, behind your firewall, just to limit your audience if that makes you more comfortable.

Also I’d recommend trying out tools that are already installed that you don’t have to maintain and install yourself. For example, I started on and paid $10 a year to map my domain name. When I knew WordPress was a good fit for me and my blogging and site needs, I went ahead and found an ISP and installed WordPress myself. And two years later, I’m hooked on WordPress and I’m even attending WordCamp Dallas in a few weeks.

Sharing content is the next step, and the final step is providing a platform for users to bring their own content in. These steps take time but you will learn valuable lessons along the way and hopefully avoid any stumbling or disastrous results. It’s okay to fail, though. You learn new lessons with each attempt and approach.

So keep an eye out for the recording of the webinar, Documentation as Conversation. The price remains at USD $20 and you get to schedule listening to it any any time of the day. It’s an hour long and if you do listen to the recording, feel free to contact me via email with any questions. I am looking forward to hearing even more feedback!


Dangerous future for technical writing?

Photo courtesy of Hamed Saber,

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.

Progress on the Conversation and Community book

The final details for my book, Conversation and Community: The Social Web for Documentation, are coming together. Lots of news to report, so here goes.

I’m so excited to announce that Eliot Kimber has agreed to use my book for the DITA for Publishers project, taking the content from Adobe InDesign to DITA.

Tom Johnson also posted a fun interview he recorded during the STC Summit. I told Tom, I can hear myself grinning. This book is just fun to talk about.

I’m often asked, how long have you been working on it? I answer that I’ve been working on it for over a year now. It combines lots of stories from my corporate blogging days at BMC Software with my foray into the open source community with the One Laptop per Child project, SugarLabs (the education project that runs the open source software on the OLPC laptop), and most importantly, FLOSS Manuals, providing free software for free documentation. My thirty-hour work week at ASI has afforded me the time to write out my journey and my observations along the way.

What a journey it has been and I’m so pleased with how the book is turning out. This week I am furiously indexing (is there any other way to index besides furiously?) and often messing with recto and verso pages, something I haven’t done in InDesign before and boy does it show. My PageMaker days as a graduate assistant at Miami University’s Center for Chemical Education are coming in handy, no doubt about it.

I think we’ve finalized the cover design, which for me is a very exciting part of real bookmaking! I’ll see if I can share it on my blog soon.

Four fine people have agreed to do technical reviews and I know some of them are at least 100 pages in. I hope they have insights – but not too many that may cause me to think too hard. Just kidding, Alan, Will, Sarah, and Scott! 🙂 Keep reading and keep your notes at the ready because I’m ready to make all the changes needed to keep this project rolling. This book’s time has come.