This post is part of a series on usability and maintainability. At first, meeting the needs of content consumers through usability can seem at odds with meeting needs of technical communicators through maintainability. My purpose in these posts is to discuss how technical communication best practices can satisfy both needs. I’ll use Gurak and Lannon’s usability criteria of users being able to “find what they need, understand the language, follow the instructions, and read the graphics” (A Concise Guide to Technical Communication, 31).

Effective Searching

Text searching has become a prominent, if not the primary, method of locating information electronically, thanks to Google and other search engines. I fall into the search camp; I may glance through a table of contents, but if I don’t quickly locate what I want that way, I turn to searching. Documentation authoring software typically provides a search mechanism for users out of the box, so this provides a bonus for technical communicators through needing little or no maintenance. I mention it here mostly because these days, when people think of finding something electronically, they think search.

Thorough Indexing

Indexing is a leftover from the days when all documentation was delivered in print and that text searching was not available. Some users rely on indexing probably out of habit. But one advantage of indexing is that it acts as a backup in case a search proves ineffective (such as when the same word has a specific meaning as well as a generic meaning in the content—in this case, the search will pick up every instance, while the index will point only to the relevant instances.

A detailed index sounds like the enemy of maintainability. However, in cases where a certain word may be used in the content in both specific and generic senses, the index can help the tech writer know where the specific instances are that need to be changed. Also, include synonyms in indexes can help in the event that project terminology changes. Include as synonyms different words that were considered for use in the application, and then if later someone up the ladder changes the term used, all the synonyms can remain in place.

Organization

Logical organization is a boon to both users and technical communicators. If we make it easy for the user to find information based on the its ordering, if we have a clear classification of information, then we make it easier on ourselves to locate it and to find a proper fit for new content. And of course, logical organization helps users more quickly locate the content they’re looking for in cases where they need to drill down from a certain point and get context along the way.

A context-sensitive help system has a built-in way to be organized. Other ways to organize documents are according to a chronological order, a procedure, logical ordering of concepts that build on each other, roles/job descriptions, alphabetically, or any combination of these. As long as the organization scheme is recognizable and easily followed, both the user and the writer benefit.

Previous: Usability and Maintainability Not So Incompatible