Online Technical Writing: Highlighting & Emphasis


Note: This chapter refers to certain other chapters that are not yet complete. Sorry for the inconvenience.

One of the problems in technical writing---in particular, technical writing about computers--involves the use of the various techniques for emphasis. Unfortunately, some technical texts go overboard on the use of the various emphasis techniques which are discussed here. This chapter discusses the following:

Common Highlighting Problems
Actually, several problems involving emphasis can occur: What is the point of using emphasis techniques? Used properly, they highlight text that readers must see, for example, alerting them to actions they must take or avoid. Emphasis techniques can make following a procedure considerably easier. But the design of the highlighting scheme (which organizes the emphasis techniques around a system of use) must be based on the reader, the tasks that the reader must accomplish, and the characteristics of the text (or the technology) that the reader is using.

Highlighting Fundamentals
Consider a few fundamental principles of emphasis: In the following discussion, you'll notice that any system of emphasis techniques can get quite complicated and hard to remember. You'll notice that there are many equally valid ways of using emphasis techniques: for example, in some cases, it's arbitrary whether you use bold or italics. To offset this complexity, you must document your guidelines for emphasis in a style guide. A style guide is simply a record of the decisions you and your documentation team have made about how you want your documents to look.

Your readers also need to be informed as to the highlighting scheme you plan to use. This can be handled in the preface: include a section called "Highlighting" or "Typographical Conventions" where you list how you use italics, bold, fonts, and other such effects. For an example, see the discussion of prefaces in the chapter on standard components of technical books

Specific Emphasis Techniques
This next section goes one by one through the various emphasis techniques, explaining the common practices.

Bold. In publishing, technical publishing in particular, usage is mixed as to whether to use bold or italics for basic emphasis. For example, if you want to emphasize that readers should not turn off the computer without first shutting it down, the "not" can be bold or italics. Traditionally, italics has been used, but, perhaps because of computers, bold is commonly used as well.

Whichever technique you use, use it consistently throughout your text or library of related texts. By the way, readers are not likely to be able to distinguish between levels of emphasis: for example, using italics for important text and bold for very important text is likely to be lost on most readers.

If you are tempted to make an entire paragraph bold, remember one of the principle of emphasis discussed above: using too much of an emphasis technique causes the effect of the technique to be lost. Not only that, but too much emphasis makes readers less inclined to read. Instead of carefully reading an all-bold paragraph, readers may just ignore it entirely!

Instead of creating an all-bold paragraph, use the special-notice format. In it, a key word (for example, Important, Note, Danger, Caution, Warning) is bolded, while the rest of the text is left regular roman (that is, the same font and style as the regular body text).

Legitimate use of bold in technical texts varies widely. As long as you develop a scheme that is directly related to the reader's need and to the characteristics of the text (or technology) and that does not lead to overkill, your use of bold should work fine. Here are some common, standard uses of bold:

You'll notice that the preceding discussion stated no absolute rules. that's the way it is: technical publishing practice is quite varied. The main idea is to develop a logical, controlled system of highlighting, use it consistently, and document it in a style guide so that you and your documentation team members can refer to it.

Italics. Here are some of the standard uses for italics:

Underscores. There is almost no reason for using underscores in technical text. In the days of typewritten text, there certainly was. However, in these times, when bold, italics and other such typographical effects are readily available, underscores look obsolete. If you want to emphasize something, use your standard guidelines -- for example, use italics or bold. Don't try to create gradations of emphasis: for example, a scale of increasing importance ranging from italics to bold to underscore will be lost on your readers.

If you see good use of underscores in technical text, it will probably occur in heading design.

Capitalization. In technical publishing, there seems to be a running battle between technical writers and technical experts over capitalization. Technical experts like to use initial caps for practically every component and process in a system, while technical writers insist on using caps for proper names only. Also, technical experts (and management) typically use all caps for text they consider important and want readers to attend to.

As a technical writer, hold the line against capitalization. Capital letters are distracting; all-caps text is uncomfortable to read. Capital letters create a busy text, which sends lots of unnecessary signals. Capital letters are traditionally intended for proper names such as Microsoft, Netscape, Gateway, Dell Computers, WordPerfect, Pagemaker, and so on. The classic guidelines in technical publishing is to capitalize the names of separately orderable products only. However, the politics of organizations bends this guideline considerably. If a company is proud of a certain feature in its new release, for example, EnergyMiser, it will capitalize it, even though you can't order it separately. This is the point at which capitalization is being for emphasis. As a technical writer, you'll want to user caps for proper names and keep the use of caps as an emphasis technique to a minimum.

Here are some typical guidelines for capitalization:

Single or double quotation marks. Quotation marks are often mistakenly used as emphasis techniques in technical text. As a technical writer, limit quotation marks to the traditional usage, which includes quoted speech; numbers, letters, or words referred to as such. Quotation marks, like capital letters, tend to create a busy, distracting text and therefore should be avoided.

Well-designed computer text avoids quotation marks rather vigorously. One of the primary reasons is that some readers might mistakenly assume that they must include the quotation marks in the commands they enter.

Instead of Use the "move" command.
Write Use the move command.
Instead of Enter "copy install installnow."
Write Enter copy install installnow.

Note: While some technical texts have well-defined uses for single quotation marks, in general there is no standard use for single quotation marks, other than the traditional quotation-within-a-quotation rule. When you see single quotation marks within technical text, there is usually no more rationale for their use than there is for double quotation marks.

Alternate fonts. One of the most common styles in volving alternate fonts is to use Courier or some similar monospaced, old-typewriter-style font in contrast to the standard body font (such as Times New Roman or Helvetica). You can create this effect in web page by using the <KBD> tags. For example, "type install to install the program."

Here's a review of the common uses of alternate fonts:

Color. Color is used in technical text but it is expensive and hard to manage through the publishing cycle.

However, color is easy to use in online information. It's common to see hypertext links, for example, using color. Online helps typically use green while web pages typically use blue for new links and purple for links the user has already explored.

The tendency to use color indiscriminately in online information is much like the tendency to go wild with bold, italics, type sizes, and alternate fonts in hardcopy information. The feeling must be something like, "It's there, it's cool, so let's use it!"

There are not any strongly developed trends in the use of color in technical text, either online or hardcopy, other than the use of green and blue for hypertext links, mentioned earlier. Printed technical texts rarely use color because of the cost.

If you want to use color, plan it carefully. Don't expect readers to remember that red signals one idea, blue another idea, and green still some other idea. Just stick to one color. In general, avoid using color for extended text. Instead of making an entire warning notice red, just make the Warning label red and leave the warning text regular roman.

Better still, read some of the standard literature on color in the technical communication field. There are general design issues and international issues:

Combinations of the preceding. In general, it's a bad idea to combine emphasis techniques, for example, bold and italics. In nonprofessional technical text, you'll see such garish combinations as all all-caps bold-italics or all-caps bold-italics with double quotation marks. Avoid these!

One legitimate combination is to use italics with alternate fonts. For example, when you show the syntax of a command, you want the entire text to be in Courier, but you also want the variables to be in italics:

copy OldFileName NewFileName

Emphasis Techniques in Computer Text
Computer texts may use some of the most complicated highlighting schemes in all of technical publishing. This may have to do with the desire to help beginning users, or it may be because computers make such techniques so readily available to writers. As of 1997, computer publishing seems to have grown away from excessive use of emphasis techniques. You may have used or seen earlier computer texts that embedded graphics of keytops right in the procedures or that used lots of color to highlight keys or commands. These busy, excessive practices seem to be fading, however.

Emphasis techniques used in computer texts vary widely. The following discussion provides an example, not a prescription, of how emphasis techniques can be used together in a scheme that is logical and that avoids overkill. Please don't view this discussion as a series of rules; instead, spend some time browsing computer manuals and guides to get a sense of how widely practice varies. (And as you browse, be critical: highlighting overkill or illogic is common!) Ultimately, you must design a highlighting scheme (a system of emphasis techniques) that works best for your readers, your text, and the tasks and technology that your text documents.

Here is a typical highlighting scheme for a user guide that discusses both hardware and software:

Although this highlighting scheme is fairly common, you may have spotted some areas of concern. For example, it might be confusing to readers for both example text and text they must enter to be Courier. They might mistake an example for text they must enter, or they might mistake required text for an example. It's considerations like these that explain the variability of highlighting schemes that you see in computer texts---along with the different needs of technology and readers.

Further Explorations
Once you've read the preceding, a good thing to do next is to explore technical publications to see what highlighting schemes they use. Watch for the way things like bold, italics, caps, alternate fonts, and other such effects are used. Most likely, you'll see very different usage than what you've read about here. As you explore, think about the logic of the emphasis techniques you see being used; try to formulate the rules that the writers seem to be using; watch for inconsistencies in highlighting; and think critically about the usage you see -- is it logical? overkill? "underkill?"

After you've done some exploring like this, the next logical step is to read the chapter on style guides, if you've not already done so. Highlighting schemes must be documented in style guides so that you won't forget them and so that your documentation team members can refer to them.

Interested in courses related to this page or a printed version? See the resources page. Return to the main menu of this online textbook for technical writing.

Information and programs provided by hcexres@io.com.
Хостинг от uCoz