Skip to main content

Tag: web 2.0

Opinion

This is the future of technical communication

First, read this article in the New York Times about the struggle to keep a reporter’s kidnapping quiet:

For seven months, The New York Times managed to keep out of the news the fact that one of its reporters, David Rohde, had been kidnapped by the Taliban. But that was pretty straightforward compared with keeping it off Wikipedia. 

Now, think about these issues as applied to technical communication. Let’s assume that your organization has online community — forums and a wiki, maybe. Technical communicators are responsible for monitoring and managing the community. Under what circumstances do you delete information? How do you respond when:

  • Information is inaccurate
  • Information is unflattering
  • Both

What if the information is accurate but incomplete?
What if someone describes a way of using your product that could cause injury, even though it’s technically possible? Do you delete the information? Do you add a comment warning of possible injury? What if the reader sees the original post but not the comment?

In the absence of safety concerns, I think that accuracy must win. Thus, as the information curator, you have a responsibility to correct inaccurate information. If the inaccuracy is truly dangerous, you may need to edit the post directly. Make sure that you disclosure what you’ve done with brackets. For example:

I like riding my scooter down mountains, especially without guardrails. Wheee! [This is a really bad idea because You Might Die. -moderator]

or

I like [really bad idea redacted by moderator]. Wheee!

Deleting unflattering (but accurate) information will probably backfire on the organization. Instead of censoring negative content, try addressing the concern being identified. Think of an impolite forum post as customer feedback. Does the poster have a valid point? Can you fix the problem that’s been identified?

I hate your scooters. They don’t come in enough colors. And they suck. 

What colors would you like to see? We do have two dozen available, see this list.
– Joe in TechComm

The life-or-death issues around Mr. Rohde’s kidnapping are relatively straightforward. We are likely to have much more difficult judgment calls in typical technical communication. Imagine, for example, that information were being suppressed because it criticized security arrangements and not because of safety concerns for the reporter. In that case, I think we can agree that Wikipedia’s response would have (and should have) been different. What would an equivalent scenario look like in your organization?

Sarah O'Keefe
June 29, 2009
Read More
Humor Opinion

More cowbell!

About a year ago, we added Google Analytics to our web site. I have done some research to see what posts were the most popular in the past year:

  1. The clear winner was our FrameMaker 9 review. With 21 comments, I think it was also the most heavily commented post. Interestingly, the post itself is little more than a pointer to the PDF file that contains the actual review.
  2. InDesign CS4 = Hannibal post, which discussed InDesign’s encroachment on traditional FrameMaker features.
  3. A surprise…a post from 2006 in which Mark Baker discussed the merits (or lack thereof) of DITA in To DITA or not to DITA

Our readers appear to like clever headlines, because I don’t think the content quality explains the high numbers for posts such as:

We noticed this pattern recently, when a carefully crafted, meticulously written post was ignored in favor of a throwaway post dashed off in minutes with a catchy title (Death to Recipes!).

For useful, thoughtful advice on blogging, I refer you to Tom Johnson and Rich Maggiani. I, however, have a new set of blogging recommendations:

  1. Write catchy titles
  2. Have an opinion, preferably an outrageous one
  3. More cowbell

Sarah O'Keefe
June 4, 2009
Read More
Opinion

Technical writing and social networks

There is an interesting thread on techwr-l about using social networking sites to deliver product information. In the thread, Geoff Hart notes there is a generation gap in those who turn to unofficial online resources vs. product documentation:

The young’uns go to the net and social networks more than we older folk, who still rely on developer-provided documentation. We ignore this change at our peril. Cheryl Lockett Zubak had a lovely anecdote at WritersUA a few years ago about how she and her son both set out to solve an iPod problem; they both found the solution in roughly equal amounts of time, but she found it in Apple’s documentation, while her son found it on YouTube.

My experience as a user straddles both relying on official docs and information available elsewhere. When my iPod locked up a few years ago, I found decent information on Apple’s web site, but the best resource for my particular problem turned out to be on YouTube. A user had made a video showing step-by-step what to do.

The dilemma of official docs vs. Web 2.0 information partially boils down to question of audience. As part of the process for planning and developing content, technical communicators should evaluate and remember the audience, and that audience consideration now needs to extend to how a company distributes the content. I don’t think there are cut-and-dried answers here; for example, it’s unwise to make the assumption that all folk over a certain age are unaware of or don’t use social networks and other Web 2.0 resources. Ignoring unofficial information channels is certainly not the solution, however.

Alan Pringle
June 1, 2009
Read More
Webinar

Documentation as conversation webinar

We have added Documentation as Conversation, presented by Anne Gentle, to our upcoming webinars. Anne is scheduled to present on June 9 at 11 a.m. Eastern time:

Even if your documentation system does not converse with your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well or learn something new as if they were in a classroom with a community for classmates. This talk describes how you can think about documentation and user assistance in a conversational way, with the help of social media technology. I’ll discuss the topics in my new book, Conversation and Community: The Social Web for Documentation. I’ll describe the use of in-person Book Sprints that combine wikis and community events to gather together writers to accomplish documentation goals

Anne is an expert, perhaps the expert, on using wikis and other social media to extend traditional documentation efforts. She’s also an excellent speaker, so I hope you’ll join us for this session.

Register for Documentation as Conversation ($20)

See all upcoming webinars

PS We are working on additional topics and looking for more speakers. Do you have topics you would like us to cover? Please let us know. We are working on a couple of sessions on document conversion.

Reblog this post [with Zemanta]

Sarah O'Keefe
May 22, 2009
Read More
Opinion

The Age of … Expertise?

Over on O’Reilly’s Radar blog, Andy Oram has a fascinating article about the demise (!) of the Information Age and what will be next:

[T]he Information Age was surprisingly short. In an age of Wikipedia, powerful search engines, and forums loaded with insights from volunteers, information is truly becoming free (economically), and thus worth even less than agriculture or manufacturing. So what has replaced information as the source of value?The answer is expertise. Because most activities offering a good return on investment require some rule-breaking–some challenge to assumptions, some paradigm shift–everyone looks for experts who can manipulate current practice nimbly and see beyond current practice. We are all seeking guides and mentors.

What comes after the information age? (be sure to read the comments, too)

It’s an interesting idea, but I don’t think we’re getting away from the Information Age into the Expertise Age. After all, expertise is just a specialized (useful!) form of information.

In the comments, Tim O’Reilly points out that the real change is in how information is gathered and distributed with “the rise of new forms of computer mediated aggregators and new forms of collective curation and communication.”

I believe that we are still firmly in the Information Age because information has not yet become a commodity product. There is, however, clearly a shift happening in how information is created and delivered. I think it’s helpful to look at communication dimensions:

  • Traditional technical writing is one-to-many. One person/team writes, many people consume it.
  • Wikis are many-to-many. Many people write; many people use the information.
  • Mailing lists are many-to-one. Many people respond to one persons’ question.
  • Technical support is one-to-one. One person calls; one person responds.

Technical support is the most expensive option; it’s also often the most relevant. Technical writing is more efficient (because the answer to the question is provided just once), but also less personal and therefore less relevant.

Many technical writers are concerned about losing control over their content. For an example of the alarmist perspective, read Joanne Hackos’s recent article on wikis. Then, be sure to read Anne Gentle’s eponymous rebuttal on The Content Wrangler.

Keep in mind, though, that you can’t stop people from creating wikis, mailing lists, third-party books, forums, or anything else. You cannot control what people say about your products, and it’s possible that the “unauthorized” information will reach a bigger audience than the Official Documentation(tm). You can attempt to channel these energies into productive information, but our new information age is the Age of Uncontrolled Information.

Furthermore, the fact that people are turning to Google to find information says something deeply unflattering about product documentation, online help, and other user assistance. Why is a Google search more compelling than looking in the help?

Sarah O'Keefe
September 5, 2007
Read More