Technical Writer's Portal

By Janis Ramey and Marlene Miller
We made a rather surprising observation as judges for the chapter's recent online competition: Several entries showed the classic symptoms of poor editing, which (we assumed) would have been a routine part of any technical communicator's documentation process. Poor editing kept these entries from the winners' circle. Their content may be (and probably is) excellent, but poorly edited entries don't win awards.

Some classic symptoms of poor editing are inconsistencies in language and format, unfamiliar terminology, cluttered graphics,
poor organization, inaccuracies in content, and a lack of consideration for the user and media.

Be consistent in language and format A prime goal of editing is to make a document consistent in language and format. So, if an idea or function is called "autoconnect" in one place, it should be called that in other places (don't change it to "enable", for example). . Formats also need to be consistent. Main headings should all look alike; subheadings should all look alike and be less important looking than the main headings. . If the company or organization has a style guide, follow it to select preferred words and formats. The guide may need to be adapted for online publications. Otherwise, use a standard guide such as the Chicago Manual of Style.

Use familiar terminology Maybe even more than in printed documents, online text works best with familiar terminology. Readers like to comprehend the text quickly and easily. They don't want to (and shouldn't have to) spend time figuring out the meaning of words. . An example we saw in the competition was on an ordering form. A customer fills in name, address, part number, etc., and then clicks a button to enter the information. Most websites call that button, "Add to shopping cart" or "Add to order." This has become familiar to on-line customers. Instead of using something familiar, the entry we judged called the button "Submit." Submit is not only unfamiliar in this context, it is confusing because a customer is not sure what will happen when that button is clicked.

Simplify graphics Graphics presented on a monitor need to be even less cluttered than graphics for print media. The monitors themselves impose constraints since many are fairly low resolution and restricted in size. Fine lines and small text may disappear. On the other hand, using color to help clarify meaning is cheap and easy. A flow chart, for example, might show one process in one color and another in a different color. Also, graphics should fit on a screen with little or no scrolling and still be readable. Editors can help simplify graphics. Editing can also create a consistent look throughout the publication.

One of the competition entries used hot spots on a large graphic to jump to context-sensitive help. We thought the concept was terrific, but the graphic itself was a problem-too much text in too many different font sizes and weights as hot spot labels. As a result, the usefulness of the graphic was severely diminished by its lack
of visual appeal.

Organize the text We found that even the basic guidelines for online text were often ignored.
Break up long blocks of text. Lengthy text needs to be split into screen-sized chunks where appropriate or at least broken up by headings, white space, or graphics.
Put pop-up text into context. Be sure the pop-up chunks, such as context sensitive help, make sense in the context they are viewed. They may not appear in any particular order so the user may need help understanding where the chunk fits into the overall piece. . Maintain consistency in format and appearance. Users become uneasy and confused if similar items look dissimilar. Therefore, all online help text should be similar in appearance so the user recognizes it as online help. Other functions, such as pop-up dialog boxes, should have a different appearance.

Check mechanics (broken links, etc.) Links that lead nowhere or to the wrong place are not just frustrating, they are confusing and interrupt the train of thought. Also, a user begins to loose confidence in the material as well as in the mechanics when they don't work. A link in one of the competition's online help entries led to a "text to come" page, which immediately told us that the entry had not been thoroughly edited. . Remember the global nature of the user and the media . Some of the entries with universal content also had a presentation geared to a select user group. .
Consider the recognized standards of online help. When users access an online help file, they expect it to do certain things. Any variations on the standard-such as embedded help or tutorial help-should be introduced and explained to the user.
Consider the global nature of Internet business. Writing should be pared down to essentials and word choice kept to the basic English guidelines. Editing can reveal words and structures that might confuse a non-native-English user. .
Make the first page work for everyone. A particularly unfortunate fault of the homepage or startup page for some of the entries was that the page was too specific for all users. For example, an acronym was used on one instead of the spelled-out name of the organization. For the uninitiated, the acronym was meaningless. Step back and look at the goal or purpose of the piece. It may need a better introduction or homepage for orienting the user. . We have a different outlook on online communications after our competition judging experience. While we still believe content is king, we think careful editing makes a winner! . Janis Ramey served as a judge in Pittsburgh's 1999 online competition. She's a senior member of STC.