Author Bio

Your Inner Tech Writer

posted: 2.22.11 by Steve Bernhardt

In the mid-eighties, I took a position at New Mexico State University, where their English department had a strong technical writing program. I had a chance to teach a course on developing computer documentation—reference manuals, user guides, and tutorials. We learned to write “how to” documentation: how to set up or configure a new computer or printer, how to use a database program to keep track of health records, or how to create computer animations. I felt slightly underprepared, but over time, I grew to like the course and eventually developed a second course on online documentation, including help systems. During the time I taught these courses, most computer documentation moved online, so that manuals and help systems (the panels that pop up on your screen when you ask for help) tended to become online hypertexts, rather than printed manuals.

I learned a lot by teaching these courses, learning that has been quite useful as we’ve developed Writer’s Help at Bedford. Writer’s Help is part reference handbook, part help system. It requires students to work online, viewing linked information on screen. Creating Writer’s Help required that we think about usability, screen design, navigation, search, and information presentation. The challenge was to take a really well-designed handbook (Writer’s Reference) and reimagine it as an online help system.

Those who write user documentation think in very particular ways about audiences. Tech writers have long emphasized observing users, understanding their situations, involving them in development, and doing careful user testing to see what works and what ought to be revised. As a result, we know certain things about technical audiences: they would rather learn from a person than from a manual, they skip over long passages, they would prefer to look at a drawing than a paragraph, they tend to enter a text in many places other than page one, and they are often frustrated with documentation. We also know a scary fact: only experts are good at using technical manuals. Only they have the language, the ability to define problems, and the ability to work between the manual and the system itself to solve problems.

When we get to know an audience, we can adapt a text to the ways that people behave. In the case of Writer’s Help, we worked on these assumptions, all based on audience research:

  • Students are more oriented toward examples than explanations, so we should make examples prominent and plentiful.
  • Students and teachers have their own language, and it is not the traditional language of a writing handbook, so we should use their language and leverage the technology (search, glossing) to bridge differing vocabularies.
  • We never know where someone will enter the text, so we need multiple paths through the text and orientation on every screen as to where one is, where one can go, and how one can retrace a path.
  • The routes to learning and problem solving are rarely direct, so we should provide links, suggest related materials, and encourage exploration.
  • Students are accustomed to browsing and searching the Web, so we should model our tools to support what they already do well.
  • Nobody wants long, unrelieved passages of text, so we should break up long passages, provide visual relief, and make information as visually accessible as possible.

We’re getting good feedback—the best, really—when students consistently say during classroom testing that Writer’s Help is easy—easy to find what they want, easy to understand, easy to use. That’s all a tech writer ever wanted to hear.

Tags: , ,


Categories: Handbooks, Teaching with Technology
You might also like: To Keep or Not to Keep
Read All Steve Bernhardt

Comments are closed.