How can we go towards documentation as conversation?

Tell me… and I will forget. Show me… and I will remember. Involve me… and I will understand.

Documentation as conversation means getting closer to the users and helping them perform well. Over the years experts such as JoAnn Hackos and Jared Spool have told us that this type of user-centered design and focus increases the quality of documentation.

H. Allen Brizee and Katy A. Schmaling wrote “Effective Workplace Writing” as a resource for the Purdue University Online Writing Lab (OWL), and they say “In the last twenty years, two important ideas have developed that help professionals compose effective workplace writing: rhetorical awareness, and user-centered design.” In my mind and from what I read, user-centered design is consistently related to Web 2.0 definitions. Where Web 1.0 merely served information blindly, Web 2.0 gives users a chance to interact with the information and each other using the web.

Taking off from the concept of user-center design, I’d like to talk about how to get even closer with real customers by starting conversations and enabling user assistance in interactions with users with a series of blog entries on documentation, conversation, and community.

Professional writers have more conversation-starting tools at their disposal than any other time in history. Techniques may include the use of blogs, wikis, forums, and social networking sites, but may also involve photos, simple stick figure illustrations, videos, virtual worlds, or instant messaging. What are your thoughts on a blog series to discuss modern methods for involving readers in the conversation surrounding technical documentation?


  • August 21, 2008 - 1:15 pm | Permalink

    Anne, sounds like a fascinating topic … but then I’m a little biased, as it fits right in with the topic of a session where I’ll be speaking at next month’s Best Practices conference.

  • August 22, 2008 - 3:25 am | Permalink

    I love the Confucius quote (I’ll be borrowing that, I think). Personally, these days, I find that I always hope software will come with instructional videos – and if it doesn’t I invariably go straight to YouTube to look for some. For me, even quick & dirty videos on YouTube are more effective as documentation than professionally produced written documentation that demands more of my time and effort. I think we need to move from thinking of ourselves as technical writers and start thinking of ourselves as technical communicators. We need to find the most effective way of engaging our audience because – as Confucius says – people are much more likely to understand something if they feel involved.

  • August 22, 2008 - 8:15 am | Permalink

    I’d like to see a resurgence of an old idea, namely electronic performance support systems, as one of the ultimate examples of documentation as conversation. Currently, developers design Wizards and writers write tutorials (I know, sweeping generalization). The problem I have as a user with tutorials is they say, “Put your problem aside for while and work on this make-believe one instead.” The more we as technical communicators can get into the Wizard business, the more we get into a complex conversation that includes the user, the application, and the user’s real data.

    This is not a counter to anyone else’s fine observations, just one more perspective thrown into the pot.

  • August 22, 2008 - 1:07 pm | Permalink

    Yes! Great idea for a series. I’m contemplating a help file right now that needs some serious reworking to make it more coherent. Right now it’s basically just a reference tool. You can search it for answers if you know the right terms – not very helpful to a novice.

    I like Alistair’s point a lot. I’ve been creating Flash demos that show users how to do basic tasks in our software. They were originally created more as sales tools – kind of a “look how easy our software is to use” thing. But users really like them.

    But to Mike’s point, when I’m the user I don’t like tutorials. I much prefer reading how-tos. I don’t like being stuck with watching a video when I can read so much faster. However, when you’re working with something that’s very complex, I think videos and interactive tutorials are great (and even I will go look for them!).

  • August 22, 2008 - 9:45 pm | Permalink

    Bob – Sounds like a great talk! I like the title, Critical Conversations with Customers … Are We Asking Questions That Lead to Answers We Need? Looks good.

    Alistair – I’m amazed that YouTube videos are high enough resolution for you to see what’s important on the screen. Then again, there may be good demos that zoom in on the screen so the YouTube 640×480 resolution is readable. But maybe screen grabs are less important than taking you through the “best” features of the software.

    Michael – I’ve observed something similar with products that need a lot of configuration in order to give you meaningful examples. I’m working on a product now that does Customer Relationship Management, and without lots of data already incorporated into the product, it’s more difficult understand what you’d do with it. For example, an association that maintains address records for a college fraternity has a home (summer) address for current students plus a school address, and home (year-round) address for alumni plus a work address. Just having that data modeled for me already makes the product come to life for me, I would imagine it would help users in a similar way.

    Rachel – I’m so much faster at reading than any other method of learning so I agree. You might be interested in this technology – at ASI I just learned that Google’s search configuration allows you to create special suggested words for search terms that users might use, to avoid them missing what it is they need. It’s like you can create a custom related terms list beyond the usual suggestions (plural, hyphen placement, and so on). Sounds coooool for tech writers for certain, especially if we’re good at the art and science of finding additional index terms.

    Thanks everyone for letting me know this is a good series to kick off! Stay tuned for more.

  • Leave a Reply