Writing Effective Introductions and Overviews

by Kasia Novak, Quill Contributor

This is a brief summary of the STC telephone seminar that took place on August 18, 2004 with Leah Guren as the presenter, and CheckFree i-Solutions as the host site for our local Southwestern Ontario chapter.

In her seminar, L. Guren reminded us of the importance of a good introduction or an overview that we, technical communicators, should include in our documentation. She talked about the purpose of introductory material and its key elements, and explained how to meet the challenge of writing a product overview and how to add value to it.

An Introduction's Role

The role of an introduction is to:

• define the scope of the subject
• identify the target audience
• explain conventions used in the document
• set the readers’ mental model so that they approach the product correctly.

A good introduction saves the reader time and effort that may otherwise be wasted by wrong assumptions about the product or the document content. And, by the way, is there anyone out there who does not read introductions?

Describe the Structure

The key elements of a good introduction include statements that describe all the chapters in the book, each chapter’s topic and content, references to related subjects covered in other books, and the overall structure of the book. The structure provides a guideline for navigation, helps in searching for information, and lists the available aids, such as the glossary.

Identify the Audience

In our current hi-tech environment, it is of utmost importance to identify the targeted audience for the book. Be specific and state clearly if the document is, for example, for application users or for system administrators. List the knowledge prerequisites of your targeted audience; for example, a UNIX programmer, Windows system administrator, or a technician, trained by the product’s manufacturer.

List the Conventions

Once the reader identifies himself as part of the target audience, he may proceed to learn about the conventions used in the book. Limit the list to those icons or graphics that are used to label or identify material and remember to explain unusual typography. Skip the common typography elements, standard-usage terminology, and those design elements that are intuitive.

Provide a Product Overview

What are the length or detail requirements of a product overview in an introductory chapter? According to L. Guren, it should be just a “teaser”, an elevator story. There are at least two reasons for that: 1) the product user is not always a purchaser, and 2) the user is busy. Under those circumstances, settle on describing the key features that both marketing and product support helped you identify.

Sometimes, it is beneficial to add a theory of operation to your product overview. In such cases you may be introducing a new technology, or writing about an existing technology that is misunderstood or misused. Another case would include a new version of a product with a bad usability record.

Include Other Important Information

In addition to the key elements of an introductory section, there is still space for adding information the writer feels is important to convey to readers. Introductions and overviews can add value to the product. How? Remind yourself of your first experience with the product. Use your observations to provide extra information that comes from using the product. Or, create a surrogate user and imagine what he wants to know. Or, use your “frustration log”, which you kept for information you tried to find in the application documentation, but could not. Classify your findings, find information parallels in your product, and add them to your documentation.

Taking this extra step means overcoming the trend of minimalist documentation and adding an extra value to the publication. Then decide if this extra information belongs in the introduction, or need only be referenced.

Conclusion

Introductions are important so remember, do not skip them, and do not be stingy with information. Words can conceal—and so can the technical jargon used by the Subject Matter Experts. Use your introductions to reveal information and provide your readers with a helpful orientation to each document.

About Leah Guren: The Presenter

L. Guren works for In Other WORDS, Israel’s leading technical communication company. She trains new writers through the course she developed herself. L. Guren also conducts seminars and in-house training for technical communicators and engineers. Her clients include many of the top high-tech companies in Israel. As a senior STC member, L. Guren is a popular speaker at STC and other international technical communication events.

About Kasia Novak

Kasia is an editor at Raytheon Canada Limited, a supplier of Air Traffic Management Systems. In her previous positions, she was a technical writer at CheckFree i-Solutions and MKS. Born in Poland, Kasia's interest in books, languages, and technology brought her into the fascinating field of technical communication.