Subscribe to RSS
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):
- Wiki as forum, FAQ, HTML editor, XML editor, or CMS?: Wiki as the new FAQ I discovered and have been meaning … 7 comment(s)
- EMC Adds Google Desktop to EMC Documentum Federated Search Environment: An excellent combination, Google search for your enterp… 0 comment(s)
- Twitter for usability testing or doc testing? Sure, here’s how: My coworker went to SXSW Interactive this year, and I m… 1 comment(s)
- Writing End-User Documentation in an Agile Development Environment: This article was original published in the June 2007 is… 17 comment(s)
Here are the most popular posts based on average daily views:
- Wiki as forum, FAQ, HTML editor, XML editor, or CMS?: Wiki as the new FAQ I discovered and have been meaning … 7 comment(s)
- EMC Adds Google Desktop to EMC Documentum Federated Search Environment: An excellent combination, Google search for your enterp… 0 comment(s)
- Love, love, <3 The Twitter Book: Wow, just got a print copy of The Twitter Book by Tim … 1 comment(s)
- Conversational robots: Move over qmail mailer-daemon*, Little MOO from moo.com… 2 comment(s)
- Twitter for usability testing or doc testing? Sure, here’s how: My coworker went to SXSW Interactive this year, and I m… 1 comment(s)
Here are the most popular posts based on number of comments:
- STC Intercom – themes and advice wanted: I’m quite flattered and humbled (and more than a little… 25 comment(s)
- Look out, updated headshots are coming: The headshots I’ve been using (including the one that s… 19 comment(s)
- Writing End-User Documentation in an Agile Development Environment: This article was original published in the June 2007 is… 17 comment(s)
- DITA and wiki hybrids – they’re here: Lisa Dyer and Alan Porter presented at last week’s … 14 comment(s)
- Arrrrrrr, mateys!: I haven’t been churning out blog posts for a while due … 14 comment(s)
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 moo.com 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 Elbot.com.
*In case you’re curious, the previous robot response winner for me is,
“Hi. This is the qmail-send program at mooseworld.org
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.
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 blogs.adobe.com. 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, del.icio.us.
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 Indeed.com 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 justwriteclick.com on wordpress.com 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?
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 a 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.
Reputation systems and patterns
On one of my web wanderings reading about wikis and motivations for contributions, I started reading as much as I can about reputation systems. Last year around this time Yahoo released social design patterns for reputation systems. Wow, that’s generous.
There’s a fascinating interview on bokardo.com with Bryce Glass. From that interview, I pulled this definition: “one’s reputation in a community is both a history of one’s past actions within that community, and a value judgment about the worth of those actions.”
Clay Shirky has an argument against even well-designed reputation systems where he instead calls for community leadership.
My limited experience with reputation systems would tend to have me agree with Clay Shirky. While I’m not much of one for “gaming” the reputation system I can see how others may be entertained by that thought. But if you want something done, there’s nothing like true leadership. And a truthiness rating.
What do you think? Are there reputation systems that work well for you? Or do you tend toward more actions when inspired by a leader?
Edited to add:
Lisa Dyer has a great post, Using community equity to attract and develop talent, talking about Sun Microsystem’s work on reputation systems with Atlassian’s Confluence wiki. She has notes from “a presentation by Peter Reisen of Sun Microsystems, hosted on Atlassian TV.” Definitely worth reading!
Love, love, <3 The Twitter Book
Wow, just got a print copy of The Twitter Book
by Tim O’Reilly (@timoreilly) and Sarah Milstein (@SarahM, user number 21 of Twitter). Thanks go to Andy Oram, @praxagora, for referring me to it after he read a draft of my upcoming book.
The layout, form factor, full-bleed color page numbers, and color screenshots and photos (Twitpics) throughout the interior are just wonderful. This design combination makes it an excellent hand-held object, worthy of being print-based! I’ll keep this one out in my living room. But I’m kind of nerdy that way.
It has important and useful information about Twitter (www.twitter.com) and why it’s so powerful. Just thumbing through it I found two things I didn’t know about Twitter (and I’ve been on Twitter as @annegentle since early 2007.) One is, it really is a big deal that Twitter removed the setting that allowed you to customize which @username replies you saw and your followers saw. There used to be three settings in the Settings>Notices tab (page , now there are none. But Twitter reversed the original policy decision, and Read Write Web gives a graphical explanation (it’s strange enough that it needs explanation.)
The second informative tip is that for the most part, people tweet the most on Tuesday, Wednesday, and Thursday. And most people, if they don’t see your tweet in the first five minutes of you posting it, won’t see it at all. I bet that the more uptake we have desktop grouping helpers like TweetDeck, the longer that tweet click-through duration will last. But even with better grouping so that you don’t miss tweets from people you really want to read, as more and more people join Twitter, it’s harder and harder to ensure you get the information you want. So you might want to think about using TweetLater to post a slightly re-worded micropost at another time.
I have to admit, I do like Chris Brogan’s idea of using the hashtag #getoffmylawn for celebrities who use Twitter in an annoying way. But better yet, have more and more people read The Twitter Book to get better and better at their Twitter use and micropost writing.
And finally, words to live by, in Chapter 3 “Hold Great Conversations.” On Twitter or any other community and communication site, it’s not about you! The best part is about contributing to the community – make a positive impact. “…the more value you create for the community, the more value it will create for you.”
Social weather in online communities
I’m writing this as the rain falls down in Austin, Texas. I’m learning that with practice, you can learn the ebb and flow of a conversation and become a meteorologist for the “social weather” that’s ongoing in a community. For an example of social weather, do what Clay Shirky describes in his description of the course with the same name at New York University. Simply make some observations next time you walk into a restaurant. Is it noisy or quiet? Slow or busy? Are there couples or groups dining? That collective atmosphere is the social weather, which I first read about on Jason Kottke’s blog.
In a restaurant you have visual and auditory cues to give your inner meteorologist a chance to assess the social weather. In an online community, you need to understand the cues that occur in writing, in emoticons, and in frequency and intensity of updates to content. In the presentation “Blogs and the social weather” at the Internet Research 3.0 conference in October 2002, Alex Halavais describes a deep dive into analysis of blogger’s discourse.
“By measuring changes in word frequency within a large set of popular blogs over a period of four weeks, and comparing these changes to those in the ‘traditional’ media represented on the web, we are able to come to a better understanding of the nature of the content found on these sites. This view is further refined by clustering those blogs that carry similar content. While those who blog may not be very representative of the public at large, charting discourse in this way presents an interesting new window on public opinion.”
While this concept may sound new and exciting, it is quite 20th century. I was surprised to learn that analyzing newspaper content to determine public opinion was researcher Alvan Tenney’s original concept in 1912. 1912!
Casual users and Power users – what type of online help do they want?
I have been scanning through some of the presentations at the STC Summit that I had to miss due to the packed schedule, and Scott DeLoach’s presentation, Best Practices for Developing User Assistance caught my eye. He has slide after slide of Facts listed based on research in user assistance. Facts from those important and difficult-to-uncover research studies in the ways people read help and read on the web. The citations are excellent!
He starts by separating out the stages of use, saying 80% of your readers are in fact the casual user (novices and advanced beginners), and the other 20% are power users (competent performers, proficient performers, and expert performers). These definitions come from Dreyfus and Dreyfus’s Mind over Machine: the power of human intuition and expertise in the era of the computer.
The great thing about Scott’s presentation is that he offers citations for each of the claims he makes, even when (and especially when) there is a slight difference in interpretation that may affect your design or writing decisions.
Of special interest to me is his claim that the Power Users are the ones who want online communities. For some companies, I wonder if that means that building an online community is considered to be “icing on the cake” and a project that can’t be funded because it targets a smaller group of users. In companies with mature documentation sets, though, it seems like building an online community with the available tools would be a natural next step for technical writers.
What do you think? Do novices and beginners want a community online? Or are communities reserved for the power user?
Anne Gentle is the author of 
