Search results

IT Author Podcast -- Two Podcasts on Flare, One on the Making of a Technical Writer, and a Dogcast on User Psychology

by Tom Johnson on Nov 12, 2007
categories: technical-writing

IT Author Podcast — based in ScotlandI listened to Alistair Christie's IT Author podcast the other day online and then later driving home from work. Alistair is based in Scotland and has one of the most enjoyable podcasts on technical communication around. If you listen to podcasts, add his podcast to your feed.  His latest episodes are as follows:

  • In Flare: the good stuff, he explains the features of Flare that he really enjoys, such as being able to integrate his own javascript and PHP scripts directly into the code.
  • In Why do we use Flare?, he and a colleague talk about Flare in depth -- for about an hour, actually, discussing the little things that annoy them about Flare, such as the visual editor.
  • In What does it take to be a technical writer (a carcast), he mentions some key qualities technical writers need, such as a curiosity for learning and understanding how things work.
  • In his May 19th Dogcast, he actually gives the podcast while walking his dog. The podcast covers the evolution of help, the need for technical communication, and user psychology.

Although the dogcast started out slow, this was the podcast I enjoyed the most. About 15 minutes into the podcast, he really hit his rhythm and started driving down into the topic that seemed to grip him most: user psychology. Users don't read manuals. The days where long, printed manuals were standard prerequisites to using technology are gone. People experiment with an application and try to learn by doing; when they need information, they search for information about the task they're trying to accomplish in that instant. Online help is critical in helping users find a single piece of instruction for an immediate need.

Users are also in a state of anger and impatience when they turn to the help. They're mad because the software has frustrated them and stopped their work. They don't want to read a manual. What they really want is someone to explain to them how to do something.

Listening to Alistair's thoughts on the user's state of mind made me think about the help we write. Why is it that we often begin a software documentation project by documenting all the tasks that users can possibly do from all the available functions of the software application? We spend the bulk off our time creating written instructions that almost no one wants or reads.

Instead, I think we should be focusing on several key deliverables:

  • Audiovisual tutorials or screencasts
  • Short getting started guides covering the basics
  • Context-sensitive online help

Further, we should begin by getting to know our user -- not through a description from the SME or business analyst, but actually contacting the user to determine the tasks they want to accomplish and the format for the help.

The Getting Started guide should walk them through the most common, basic tasks the user will need to perform. This guide should be easy to get through. Alistair says the help should provide immediate rewards to the user. Take them through some quick wins. In the Getting Started guide, you give them easy-to-perform tasks that make them successful.

The screencasts (which should also be short) provide a range of other benefits, such as providing the experience of a friend showing them how to use the application.

The context-sensitive online help gives the user immediate information about the task at hand. The online help also provides a searchable database for answers.

So often we begin with the comprehensive manual in mind, when that's the last priority for users.

Additional Resources

A few months ago I posted some notes from a Kathy Sierra presentation that talked about the user's state of mind as well.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.