Friday, March 29, 2013

Documenting customer research

All too often, in-house customer research efforts are ineffective because the results are poorly documented. My rules of thumb are:
  • Write up your results as soon as possible after conducting research. No matter how good your notes or recordings, you had "ah-ha" moments that you won't recall later.
  • Write your results in an effective way. Make the important points resonate. Don't bog down your report in useless details. When writing up one-on-one interviews, think of it as writing personas. Think of it as telling a story.
  • If you archive your results in a PowerPoint presentation, make use of the Notes feature to fill in all the information that you impart verbally. Think of the deck as an artifact that will be read on its own.

When I started working at one place, I learned that my manager had done a round-table discussion with customers the year before. I asked if I could read her results and she said that she hadn't written anything because she recorded the session. I listened to the recording, but the way the mike was placed I could only make out what she was saying: the customers were largely inaudible. It was clear that I was the first person (including her) who had bothered to wade through the three hour recording.

This recording-in-place-of-report seems to be a common problem. Recordings are supplemental to reports, not a replacement for them. Whether audio or video, recordings can be very useful when snippets are excerpted and presented. They are also hugely useful for writing reports. But in almost every case that's the end of their usefulness.

I have frequently found that the only report of a research study is a PowerPoint presentation, with lots of cute photos, lots of headings, and virtually no results.

At the other end of the scale are the faux scientists who write hundred page reports filled with large pie charts, with numbers reported to four decimal places (NO decimal places, please!), and a complete lack of understanding of how to report results of research where the sample is not representative of the population.

Even the most dismal interview can be useful if the results are well-presented. This isn't about window-dressing. It's about ferreting out what's important, and as with most things, it requires hard work to be successful.

Thursday, March 21, 2013

Documentation as web sites

Those of us who write online documentation have an opportunity to move beyond the old book style of technical writing. Instead of writing books, we could start to think about whether we can present our documentation as web sites.

Instead of an opening page that has the date and a copyright notice (or whatever your HTML opens to), you could create a web page that is interesting and engaging, containing:
  • A mix of types of information that draws people in and makes them want to read: a section on samples or case studies that are interesting to read through; a section of videos; and so on.
  • Subtle but consistent and informative use of metaphor, such as visual clues that complement navigation.
  • Quality art/photos that create a mood (not icons or clip art).
  • Playfulness, creativity, and a focus on making people want to read the site.
When architecting doc web sites, I'd like to see writers considering good web site design principles. For example:
  • Creating headings that use dynamic action verbs; headings formed as questions; and intriguing section titles such as "Try me".
  • Chunking content based on reader needs (such as new/not-new, inexperienced/experienced, or UI/API), rather than organization by typical content-based chapters.
  • Providing a seamless mix of content from all sources.

I haven't mentioned providing the opportunity for reader participation and feedback only because I think we're geting a good handle on that in the industry, and it's a given.

It's vital to note that none of this should be frivolous or have a marketing bent. None of this should feel like a bells-and-whistles approach. All of the effort should be focused on helping readers absorb and retain information.

The site should first and foremost be informative, and it should contain reference materials, numbered lists, detailed conceptual info... but content should not be included just because it covers everything that could be said. Content should be included only when it's needed by readers.

The whole thing could be written in topics and single-sourced into both the web site and a more standard structure in a PDF. Single-sourcing could also be used to repeat content in more than one place on the site.

There are problems to overcome with tools and with browser support. There are possible pitfalls: we don't want to create something that's busy, causes navigation problems, or is annoying. But I think this could be done.

Speak French?


Cirque du Soleil is advertising for a technical writer. They call the role "Documentalist".