Monthly Archives: May 2008


Can online help show “read wear?”

I’ve been re-reading Jakob Nielson’s Participation Inequality essay on, and the suggestion to some how show wear marks on content struck me this evening for some reason. I guess it’s because I’ve been working on Drupal recently, and discovered that Drupal documentation contains site recipies in the Drupal Handbook. What a nifty idea. Stick with me, these two concepts are related through a recipe and cookbook angle.

Part of Jakob’s treatise on inequal participation in online communities is that you can do little to overcome the typical contribution stats of 90-9-1, although one of the suggestions is to make participation so easy that you don’t even know you’re contributing. Case in point – Amazon’s “people who bought this book, bought these other books” recommendations. Sounds like the easiest contribution ever – data mining and analyzing, then giving the data back to the shopper in an understandable format.

Jakob says, “Will Hill coined the term read wear for this type of effect: the simple activity of reading (or using) something will “wear” it down and thus leave its marks — just like a cookbook will automatically fall open to the recipe you prepare the most.”

What are some similar examples of displaying read wear from the online help or user assistance world? The first example that comes to my mind is a wiki’s “most active pages” feature that shows the page with the most edits. However, the page with the most edits may be more controversial than truthful, so the most popular pages would be more useful than touting pages most active.

How else can you show read wear on a website? You could also show the most searched-for terms when the user searches. Concepts may be more easily connected when you understand what others were searching for.

Or, rather than showing search terms, show the most recently viewed knowledgebase articles or most popular articles. I know I’ve found that useful in the past when searching through BMC Software’s rich knowledge base.

Just like CNN and other news sites offer a listing of the most emailed stories per hour, you could show the most emailed online help topics if your system offers the ability to email topics.

The ability to rate an article is included in many online help systems, and exposing the ratings to the reader would help in determining how “well-worn” a help topic is.

Tag clouds can display read wear as well, as I just realized while looking at the WordPress FAQ starting page – tonight, the largest tag is “Images.”

I’ve distilled it down to popularity, time spent on the page, rating on a page, and number of edits from strongest to weakest indicators. What other factors matter in an online help system?

Finding and following conversations – applicable for technical writers?

Bryan has the following ideas for finding and following conversations, and I think these are quite applicable to our role as technical writer also. The only item I find wanting in his post is – what keywords do you use? My initial ideas are: product name, keywords for the problems and solutions that your product addresses, and company name. Perhaps even the job titles for people who use your product like I’ve blogged about previously.

Finding and following conversations

  1. Search on Google Blog Search
  2. Search on Technorati
  3. Use an RSS reader such as Google Reader
  4. Start subscribing and listening to podcasts through iTunes
  5. Subscribe to Google Alerts
  6. Reading blog comments
  7. Jump onto Twitter and establish a presence in Facebook

I found an excellent case study of technical writers engaging in conversation through Dee Elling, who is the tech pubs manager for a programmer’s IDE. She has a blog post called Help on Help where she gets lots of comments from users – some of whom are in her camp, others who are ready to go to battle for the help content, namely the code examples that had mysteriously disappeared between releases.

Dee answers honestly and really empathizes with their need for those examples, and has a plan in place for replacing them. Her blog post is a great case study for how to have ongoing conversations with your customers.

I’ve been thinking about the writer’s interaction with customers a lot lately, because of blogging and podcasting and wikis other social media pursuits that seem to lead us towards documentation as a conversation with customers. As Tom Johnson found in his Web 2.0 experiment, some users think that the help system has boundaries. How can we break down those boundaries (seems like search is part of the answer)? How could Tom have ensured that his customer sought out conversation rather than answers?


Giving the subject matter expert a voice

I just completed a three mile run with the voice of Joan Benoit Samuelson in my ear through the techonlogy offered by iTunes and iPod and Nike’s iTunes store.

Joan Benoit Samuelson is a famous US female marathon runner, and winner of the first women’s Olympic marathon. She is most certainly a subject matter expert for female long distance runners. She gives relevant tips during certain sections of the 30 minute mix of music and voiceover tips from Joan, from how to find a pace to relaxing your shoulders and finally discussing how to vary your foot stride depending on the terrain, flat or hilly.

I couldn’t help but think of how this is an excellent example of how to incorporate subject matter expertise in new ways – it’s sort of a podcast mixed in with a mix of excellent music. Now I’m wondering how screencasts could incorporate subject matter experts voice-overs, or perhaps ways of having a “famous” subject matter expert be involved in your wiki through article contributions or just commenting every once in a while. And a podcast mixed in with a screencast offering might be a neat experiment.

Tom Parish just pointed his Twitter followers to a great blog post about Nike’s community strategy and how well it’s working. I’m a complete believer in what they’re doing. Plus, I think this example also shows that some of this community building only can happen with experimentation. Nike basically allows the community to use the platform as they wish. For example, one of the unexpected things that happened is that runners found each other for runs in real life, and quickly. Plus, the online communities that are popular are the ones where people challenge each other, such as College X vs. College Y.

Community as an added value for the technology. Neat.

I just had to share how helpful it can be to have a true “famous” recognized expert insert or splice their contributions into regular content. As technical communicators, perhaps we can enable or design that sort of voice or community into our deliverables.


The state of free documentation

That’s free as in freedom, and today’s post includes a link to Adam Hyde’s blog entry of the same title on FLOSS Manuals and some response based on my experiences so far.

Floss Manuals

What motivates people to contribute to documentation projects for free? Is the documentation actually free as in no-cost? I’ll speak from my own experience and draw from recent research in this area. Plus, I just read Chris Anderson’s excellent essay on free as a business model and learned about the multiple economies and values and currencies available to us today such as the gift economy or labor exchange.

In my Wiki-fy your doc set presentation, I talk about the motivations for people contributing to any online or community documentation, and these four categories apply for any online community, be it a wiki or a mailing list:

  1. reciprocity
  2. reputation
  3. efficacy
  4. feeling like you belong or identify with a group or cause.

These four categories explain why people are motivated to contribute for no pay (for free) to a documentation project. This poster presentation for a “General Online Research” conference 2008, GOR 08, offers even more insight into contributions to Wikipedia as well as reasons people cite for not contributing content but reading only. Now, I agree with Stewart Mader that “your (enterprise) wiki is not Wikipedia” but there are lessons to be learned from Wikipedia as well. Take a look at what they found motivated contributors:

Rank Motive
3.71 Free access to knowledge for everyone
5.15 Task enjoyment / Fun
5.33 Learning
6.55 Belief in the future of Wikipedia
6.69 Existing information was inaccurate
7.25 Quality improvement of Wikipedia

At the unconference last week, Tom Johnson asked me, why did you get started with documenting the OLPC project? My initial motivation was that someone who I used to work for asked me, and he works for Joann Hackos. So reputation was one motivating factor, but as I read more and more about the education goals of the OLPC project on, the more I saw it as an opportunity to identify with an education cause especially as related to my own kids computer educations and expanding their horizons beyond Windows. Why are any of us interested in documenting a complex product or process? It’s possible that at the heart of our motivation is recognition or reward in terms of money or success. But, an underlying motivator for many technical writers is that we like to help others learn, which ties into my education motives. We may also think that writing and communicating with images, audio, or video is a great way to make a living. What I am observing more lately is that community members want to write or share content as well.

Last year, O’Reilly ran a survey asking about the motivations that people have for contributing to online documentation, be it via a forum, a mailing list, or a web site. With 354 responses, I’m sure there’s a wide variety of answers, but certainly some patterns emerged. Andy Oram dissects them in a five plus page article. My favorite line on the first page is “And while fixes to particular errors are easy to convey, best practices are not.”

His report contains many findings that are unique, because no one else had been asking the questions. What he found that surprised me was:

  • People surveyed don’t think they are contributing to the documentation
  • People surveyed didn’t think of themselves as writers

Indeed, community building is the more important ranked reason for contributing to online documentation, rather than personal growth.

I have seen that rather than the monetary gains you can make by freelancing documentation, the currency of community is a payment schedule all on its own right.

The “free” offerings represent a shift in thinking. It’s not that no one paid for the doc to receive it. Nor did anyone get paid to write it. But the infrastructure in place enabled a sense of free-ness, freedom, and lack of cost. In reality, an elite group of people who have computers (starting at US$600 or so) and pay US$40 a month for Internet connections trade in t their time and knowledge in hopes of getting repaid in time and knowledge, recognition, a sense of belonging, or a payback in time by being more efficient.

This shift represents a new economy for documentation. Payment is in a different, “free,” no monetary cost form.


DocTrain West 2008 – How was the unconference?

In a word – energizing! I had completed my two shared talks – the Wiki roundtripping talk at 2 in the afternoon, with the next talk being at 3:30 when I moderated the Meet the bloggers panel. I had been on my feet for nearly all of both talks, and I was tiring mentally as well as physically. But the informal freestyle nature of the unconference was just what I needed to finish up my day.

Here’s how it “went down.” After the Meet the bloggers panel, Lisa Dyer and I started writing the “presentation” titles from the wiki page onto a white board and placed it outside the unconference room about an hour before the 6:30 start. I talked to people who came up and had questions about it, and also lamented the fact that we were at the same time as the Vancouver STC meeting, which was going to be held in the room next door to ours. Last week I sent their president an email apologizing for the scheduling, saying that they would have been such a fun group to unconference with! So, note to self, if I ever do an unconference again, try to match up with the locals’ schedule.

The unconference schedule, loosely defined on the white board
We had about fifteen people to start with people coming and going. We had problems with the overhead projector, but pulled it together finally on Lisa’s laptop. She demonstrated her DITA to Confluence wiki build process, and said that she’s ready to get it bundled up as an Enterprise Wiki plug-in if there’s enough outside interest. She needs to get resources for the final steps of getting it ready but it sounds like she’ll be able to do that. Lisa has had DITA in production for four years and the DITA-to-wiki workflow in place for over a year now. That plug-in should be valuable as a tool for making structured authoring work for wiki output.

I presented the wiki-based documentation used for the XO laptop simplified user guide, showing both the one-page version as well as the wiki version that also has a PDF output. I wanted to demonstrate the Sugar operating system using my Dell laptop in emulation, but I couldn’t get my laptop to display on the overhead projector. The same thing happened at the earlier afternoon wiki presentation, darn it, but fortunately Stewart Mader set us up on his Macbook for that preso. Yay Mac. 🙂 I also spoke with a localization expert who may have ideas for tapping into the translator communities that would like to work on documentation translations for the OLPC. That is an exciting outcome.

Stewart Mader did a neat mini-workshop-type session where he asked us all to share our daily tasks when working on documentation, and then we each brainstormed about the bottlenecks for each task. For example, I often read what are essentially threaded discussions in our bug tracking tool to try to determine what’s changed and whether the change affects documentation. A bottleneck is often the time it takes to read through the threads. We talked a little bit about how wikis are a better collection for information sometimes than threaded discussions – not that a wiki is the fix in my particular case, but it was good to recognize a threaded pattern and know its limitations.

Tom Johnson did two quick demonstrations of Woopra, a blog statistics tool that helps you communicate with your blog’s readers while they’re viewing your blog. Someone from New Dehli, India, was viewing his site while we were unconferencing! But he or she didn’t respond to Tom’s initial Instant-Message-like talk request. Next he showed us the marvelously simple and easy to use screencasting software, Jing. This bright little sun icon appears over your desktop and you just plug in your microphone if you want to record sound, click the little sun, drag the cursor to define the area of the screen you want to record, and you’re screencasting! Very handy, very free tool (so far.)

Alan Porter had something come up so that he couldn’t present his publishing-doesn’t-have-to-be-last scenario, and I originally thought I’d fill in with some stupid RSS tricks, but we decided we didn’t need to fill in the time and the beer-thirty hour was approaching. 🙂 So, for posterity’s sake, here are the RSS tricks I know:

  • Get updates from podcasts and video sites.
  • Get the “buzz” on blogosphere via RSS – aggregation of information is crucial for this
  • Notifications on classified ads for specific search words (craigslist has this, and I’ve often used to to seek Thomas the Tank Engine goodies)
  • Track group conversations via RSS instead of email (such as Yahoo Groups, which offers RSS feeds for conversations)
  • Do package tracking (nifty! especially for ebay resellers she says this is a useful tool)
  • Receive product newsletters (again, RSS as an email alternative)
  • Job listings aggregation using keyword searches and a location limiter (
  • Use on calendars to get notification for birthdays, anniversaries, etc.
  • Subscribe to RSS feeds from higher education institutes to get notification for course information
  • Get RSS results of searches for competitive intelligence and other specialized information, such as subscribing to a feed that searches for Anne Gentle or Ann Gentle (and I should probably add Anne Gentile, ha ha!)

As our finale, Scott Nesbitt and Aaron Davis presented about Open Source Software’s uses for creating documentation deliverables and it was an engaging little back-and-forth dialog between the two of them, much in the style of their entirely enjoyable podcasts on DMN Communications!

wiki writing

DocTrain West 2008 – Darren Barefoot – Social Media 101: Now Everyone’s a Technical Writer

Here are my notes from Darren Barefoot’s talk, a self-described recovering technical writer.

He leads with what defines social media? Create your own definition around these concepts:

  • Conversation – comments on large media sites allow ayone to speak to the media person keeping on the pedestal
  • Collaboration – 7 million people collaborating on wikipedia, likely the largest collaboration in human history
  • Sharing – some sort of microbroadcasting is built into every type of website
  • Scope – there are no longer 42-minute hours on televisions. Your buckets of stuff and time are sliced and diced. Ebooks can be 10 pages to 1000 pages.
  • Community – constructing affinity groups is easy, accessible
  • Transparency – blogging encourages transparency – medium is the message
  • Authenticity – example of knowing it’s fake is, Lonelygirl15 is an example of outed fakery

42% of Chinese internet users have a blog

“The people formerly known as the audience”The people formerly known as your audience

Survey of 1200 bloggers – why do you create content, do social media? Talk to friends and family first, Keep personal history, Emote top three. But make money bottom response.

How to use a Wiki – video showing how to collaborate without using email (yay).

Updated to add: How to use Twitter – video showing how friends use twitter to keep up with each other between blog posts (these are awesome videos, I now love commoncraft)

An excellent, engaging talk, with the conclusion being, there’s no way to relinquish control, it is already too late.

Here are the takeaways he left us with:

  • Relinquish control – realize that the best documentation for your product is already not on your website.
  • Users will help each other – put screenshots in Flickr to make it easy for your users to grab them and use them in their own doc
  • Empower your most passionate users – for example, the Red Room Chronicles created by a Marriot business traveller. He must be the most passionate hotel user known. Offer those users previews, invite them to focus groups, make them feel special.
  • Think outside the page – Twitter troubleshooting tips, and of course, remember video and photos.
  • Go where your users are – find their community spaces, be present as needed.
  • Relinquish control – again. 🙂
DITA writing

DocTrain West 2008 – Joe Gollner, XML in the Wilderness

Here are my notes from the morning keynote with Joe Gollner.

This session was a wonderful kickoff for the conference. For the first time, someone was able to connect for me that XML enabled Web 2.0 connectivity. The social web is a direct result of XML allowing for easy combinations and the participatory web. He had many nice diagrams throughout history proving his point, and I really appreciated him making that connection.

He began with a description of Saint Jerome, calling him the patron saint of content management, er, librarians. Saint Jerome was a monk librarian.

A funny game that Joe played with an XML group was, “Who came to XML from the most unusual background?” This game came after Joe showed a picture of his car with an XML license plate, humorously proving he had “arrived” in XML. The third place winner was probably Joe, who has been part of the Canadian artillery. The second place winner was a former prison guard, and the first place prize was a former surfer pottery maker.

During this session, I was reminded of the Washington Post article that John Hunt pointed out at the March DITA User Group meeting, Re-Created Library Speaks Volumes about Jefferson. Jefferson did mashups of books by tearing them apart, even different language books, and then would bind them into new books – reassembly of content 200 years ahead of his time. In 1815, in order to protect his collection after a fire, Jefferson sold his library to Congress for $24,000, the price that Congress felt was reasonable. It became the Library of Congress, a U.S. establishment that as one library says in the article, “These are the books that made America.”Jefferson had created his own taxonomy, using the terms memory, reason, or imagination. Wow, are there parallels to reference, concept, and task? Well… task may be from a stretch of the imagination for some products but hopefully they are ground in fact.

A great start to an excellent conference.


DocTrain West 2008 – Bob Glushko, Document Engineering

Bob Glushko blogs at, great blog name and a fascinating presentation. I liked that he shared and described his semi-retirement as verbalizing his desire to be a beach bum to his wife, but his wife said, I still like my job and I want to work, so go get a job! He has been teaching at UC Berkley ever since. 🙂

Building information supply chains – example of the E. Coli scare in lettuce in March 2007. Basically had to figure out how to track heads of lettuce, similar to tracking heads of people to avoid long lines at security in the airport. With enough data tracking – input and retrievability – you can make informed decisions.

Common themes of new information services – document exchange, patterns, similar to supply chains and distribution channels. There are hidden documents in business processes.

His “ah-ha” moment? he had always focused on the document, but with ordering on the web, his user experience is what really matters – did the business process work? Did the lobsters arrive dead or alive? Did his shipment get to him in time and was it the right order? You have to know the back-end, the time difference, the travel distance, the choreography and design of the pattern determines success and a happy user experience.

I’m reminded of the fact that there are 39 time zones in the world, and for collaboration across the world, we have to figure out the time zone difference relative to the person you want to collaborate with.

Bob offers an excellent analogy for wiki-based, community-collaborative content – a restaurant’s lines of visibility. At McDonalds, you have backstage production lines for food prep, at Benihana you have food prep as part of the entertainment right at your table (remeber that onion volcano so expertly prepared?) We should try to strategically determine where to draw our lines of visibility – what point of view do we wish to present to our users?

Ah, now he’s talking about a cooking school where the kitchen is the front stage for the cooks, and the back stage for the customers. A restaurant’s dining room is the front stage for the customers, but the back stage for the cooks. I’m reminded of a webpage I read where people proved that writing on a wiki actually helps you learn more about the tasks because you have to figure out your conceptual understanding of the task to write about it. If you allow more writing to happen next to the backstage when it’s the cooks in the kitchen, or the expert writers in the wiki, more beginners can learn by not observing or reading but by actually participating in the writing itself.

While you may have identified more with either the front end or back end design issues, you can choreograph the information experience for the user.
Here are Bob’s slides, also found on


DocTrain West 2008 – RJ Jacquez, Bringing the Video Revolution to Technical Communication

For the first time in history, there are four generations in the workplace. Adobe is working on technologies that bring elearning to the newest working generation. Adobe is hosting a virtual tradeshow in Second Life tomorrow, May 8. I can’t find a link for more information, but his slide showed it would be staffed from 9am PST to 4 pm PST. They want to welcome the new generation and meet their expectations.

RJ showed embedding video into PDFs – plus showing the 3D animations of a brake disassembly imbedded in a PDF file, very cool demonstration. It drew a round of applause, even. I really appreciate that there was no additional plugin to download – it just works.

Also demonstrated Adobe AIR applications. There is a list of AIR applications at, and come to find out, Twhirl is an Adobe AIR application that lets you post from multiple Twitter accounts – a use case that my coworker and I were discussing just last week. What if you wanted different Twitter accounts to follow different groups of people? For example, I could have an ASI Twitter account and only follow ASIers, an OLPC Twitter account that tracks OLPC happenings, and so on. I did finally come to the conclusion that I don’t necessarily need to compartmentalize all of my online activities, I guess – the more of “ourselves” we put online, the bigger the overall picture that people can get of me. Just like smalltalk in the office, Twitter can be the smalltalk/water cooler area for “web worker” employees. Twitter is useful for conferences, also, and we’ve started a #doctrainwest tweme that you can view on the web.

Another tidbit from RJ’s talk is that Youtube dominates Internet video more than Google dominates Internet search.

More posts to come from DocTrain West, so stay tuned.

Collaboration with asynchronous communication – getting to know “you”

While gearing up for different conference trips and presentations, I’ve been trying to get to know collaborators using asynchronous communications, such as listening to Char James-Tanny’s podcast on She presented “Virtual Ways of Communicating” at a Florida STC meeting and Tom Johnson recorded it and posted it later.

I really enjoyed not only listening to Char speak but also hear the audience questions and interactions. For example, when she showed tag clouds, one audience member asked, does the size and format of the tag words change when a tag is used more often than another? And I thought, wow, I’ve always assumed that is exactly how it works, but haven’t actually asked the question, such as refresh rate or what relative sizing means. It points out to me that I take a lot for granted in the Web 2.0 world due to observing so much of it so often. But, a new fresh perspective offers me the conceptual details that people would seek when first exposed to something like a tag cloud.

As part of listening to this podcast, I found many suggestions for cool videos, popular wikis, and new uses of RSS such as RSS that I hadn’t heard yet. I realize that no matter how hard I try to keep up, there are new applications of technology coming in every day. I thought I’d collect these together though as a nice collection of “have you seen this?” which may not make much sense unless you listen to the podcast, but these were enjoyable to hear about and explore on my own.