Search results

10 Things I Learned from My Last Podcast

by Tom Johnson on Feb 2, 2009
categories: technical-writing

The last podcast I recorded, on "Make Your Help Indispensable, Safeguard Your Job," with Mike Hughes, was so full of good information about how to make your help more valuable and user-friendly that I couldn't help but write up notes on it. Here's a list of the ten things I learned from my last podcast:

1. Make your help a mile wide and thirty seconds deep.

Users spend about 30 seconds on a help topic, so keep it short and get right to the point. On the other hand, try to cover as many of the problems users encounter as possible.

2. Don't document everything. Instead, focus on the context of the user's problems.

Avoid the trap of trying to provide "complete" instructions that don't address problems users will likely have. Long introductions, tables of buttons, menu explanations, and other information not directly focused on the context of users' problems will lead to unnecessary information glut.

3. Put help where users perform tasks.

Users need help in the application, so that's where the help should appear, not in a separate training system. When you separate learning from work, users are less likely to stop work and turn to another system to learn. The tasks they do and the help for those tasks should be integrated in the same user interface.

4. The research about the usability of help is that people don't use help.

Research about how people use help often specifically prompts them into a help file, but the natural tendency, without these prompts, is for users to ignore the help altogether.

5. Avoid obvious instructions.

If you can figure something out on your own, so too can the users. Let your help focus on the true problems that users will encounter. Look for points of paint and information gaps on each page. Ask yourself, where am I getting stuck? Where will users get stuck?

6. Search results are a great opportunity to include help.

An empty search results set is a perfect place to include links to help, such as FAQs or top problems, because users are specifically looking for help content. Many times help authors neglect this space.

7. Quick reference guides are read more than marketing material.

Users are more apt to read quick reference guides than marketing material. If you need to get a product message across, it might find more readership embedded in the quick reference guide.

8. Phrase help links as short questions in the interface.

Help links and buttons are practically invisible to the user. But if you phrase your help as short questions in the interface, users are more likely to click them. When you do this, be selective about how frequently you implement the question links.

9. Tools and technologies can distract you from what matters most: the content.

Sometimes spending too much time implementing bells and whistles that tools provide (for example, javascript drop-downs and custom skins) can remove your focus on  the content. DITA allows you to refocus on the content, since you no longer can control formatting (once you set it all up).

10. Almost everyone has a microphone for their computer.

This is the fourth podcast I've recorded that's a "double-ender technique," where both the interviewee and I record individually on each of our machines in Audacity and then I overlay and sync the two tracks. I've found that almost everyone seems to have a microphone and doesn't have trouble recording in Audacity. Previously, I'd assumed this technique required too much from the interviewee.

Additional Resources

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.