Writing Engaging Technical Documentation

Engaging technical documentation isn’t written by Tina the Brittle Tech Writer. Who is she?

She’s the technical writer in Dilbert’s engineering department. Tina believes any conversation within hearing distance is intended as an insult to her profession and her gender. She strives to maintain her dignity while surrounded by engineers who don’t have a proper respect for her work.

Tina cares more about defensible positions on the engineering department than serving the customer. I love it when I hear people say, “I no longer work for development. I work for the user.” They say it with disruption and evolution in their hearts and minds. They fully intend to serve the user the best they can.

Of course, even the best laid plans can get thrown out the window in a tech writer’s daily work. But here are some ways to engage users with technical documentation. If you’re skeptical that these techniques are effective, go straight to the content analysis of user ratings. Helping 800,000 users in a year is an impressive number.

Go beyond text

People are drawn to images on a computer screen. The Community Roundtable has a great report available that you can glean many content best practices from. For example, the report indicates that “People seldom form relationships with text alone.” Boy, that’s true, and should compel us to incorporate pictures or a video.

I know, I know. Screen captures are a pain to take in the first place, and hard to maintain over time. Let’s think outside the box for a moment. Another way to incorporate images is to use artwork, however simple or stylistic. Take a look at this watercolor created by Oceana Rain Fields, a participant in this summer’s workshop at the Rural Design Collective web site. Illustration used under the CC Attribution 3.0 license (credited to Oceana Rain Fields with permission).

This image sticks with the readers of the manual, especially kids like the child-like figure shown. It should help the users identify with the manual (available online) and get cozy with it.

A friendly, helpful, and confident voice goes a long way in building a relationship in this asynchronous conversation. Screencasting, where you narrate while demonstrating a software feature, is one way to go beyond text in user assistance delivery. As an example, WordPress.tv offers screencasters and users a voice by enabling video uploads to their site. They pre-seeded the site with about 20 professionally-created videos, but after that, users were encouraged to upload videos.

Write informally

Michael Verdi, the content manager for support.mozilla.com (SUMO) has an excellent slide deck talking about Awesome Documentation where he describes some writing style choices they made recently to “Engage the Brain” including inserting humor or surprise and writing conversationally, such as “Can’t decide on just one page? No problem. Firefox lets you set a group of websites as your home page.”   Janet Swisher noted on the FLOSS Manuals discussion list that he also rewrote pages to not just answer what you can do, but why you’d want to do it.

Measure and adjust

Copywriters for campaigns know to do AB split testing – try out two brochures or two web pages on a sampling of people in the database. See which copy and design does best, then stick with that messaging until you see a drop off in use of the information. We don’t employ that technique often in technical communications, but as our copy becomes more web-enabled, I think we should start.

For example, some of the rewrites to pages on the support.mozilla.com (SUMO) site had measurable impact to the helpfulness of the page. For two of the rewritten pages, ratings were enabled. They could measure a 13% increase the number of people who clicked “Yes” for “Was this article helpful?” at the bottom of the How to set the home page article. Because of the high traffic on their site, that’s over 1,000 people per day. Given the number of people who view that page and the similarly-edited Profiles page, the two re-written pages were helpful to 800,000 more people per year. This demonstrates the power of web analytics, especially on high-traffic help sites! This example is fantastic.

Comment and be commented upon

I have many ideas for implementing comments in nearly any online help system in my article on the WritersUA site titled, Putting the User in User Assistance. Comments connect users to each other and to the authors of the content.

Enable storytelling

Your users have stories. Can you find them with some online searches to discover a hurdle they recently cleared or a snafu they’ve found? While case studies are typically under the purview of a marketing department, try to let users tell their stories, or find a way to showcase user stories periodically by linking to their blogs or tweets.

What other ideas do you have for engaging users with documentation? I’d love to hear more ideas.


  • August 10, 2010 - 3:55 pm | Permalink

    This is a great list, Anne. I don’t think you’ve left anything out. I do think that “enable storytelling” is in its infancy, and that in the near future we’ll be able to insert the user (customer) right into the story — much like we see today in the world of gaming.

    Even for written documentation, with the rapid evolution of feedback mechanisms that let us collect data about customers, I can easily imagine targeting information on a per-customer basis and tailoring it to the steps the customer has actually performed. For example, instead of referring to a generic database server we’ll be able to include the name of the customer’s particular database server. Maybe even say “No, no — not the red one. The blue one!” 😉

  • Pingback:   How a mouth-watering user guide got me to rethink technical communication by Communications from DMN

  • Pingback: Faking a Short Document | Save the Semicolon

  • Leave a Reply