It has been shown that readers mainly read your technical documents when they are seeking answers to questions or problems, so they want to find them fast. Thus, the organization of technical content is crucial for users to find what they need quickly and easily.
To produce well-organized technical information easy to find, you can follow these guidelines according to the organization, retrievability and visual effectiveness:
Organization
This means that all the parts of the text should be coherently arranged so as to make sense to users.
- First of all, you should organize information into separate topics by type in order to provide a consistent structure so that users know what to expect. For example, if all of your API methods consist of an introduction, descriptions of parameters, examples of request and response, and error code, users know what to expect in an API method.
- You should also organize tasks by order of use because tasks are generally completed in a certain order. If tasks are not logically organized, users may waste time and become frustrated and may make mistakes or lose work.
- It is also recommended to separate contextual information from other types of information. For example, you can provide contextual help by using pop-up messages for controls and fields.
- Another way to produce a well-organized text is by emphasizing main points and subordinating secondary points. To emphasize the main point, for example, you can place topics or words first in the heading or title, in the introduction, or in the first sentence of a paragraph, or you can also use repetition or reinforcement keeping the user’s mind on the point throughout the text.
Retrievability
This involves presenting information to enable users to find what they need quickly and easily. There are several tools that contribute to good retrievability:
- Today most documents are published on the Web, so you need to take into account navigation and online searching. By facilitating good navigation and online search tools, your readers would be able to move between topics and within pages and websites to find just what they need. They are also oriented and aware of their current location.
- A complete and consistent index should have entries for every important subject that is covered in the information. For example, verbs can be effective index entries, especially when they are specific and describe tasks or procedures, such as “creating a user account”. But users are not going to look for creating in the index, but rather “User account” and then, the corresponding action.
- A table of contents should provide an appropriate level of detail and the top-level hierarchy which allows users to see at a glance the main topics.
- Online links and cross-references are essential in technical information as they provide information about and access to related topics and allow good navigation within the current document or Web site.
Visual effectiveness
It provides the necessary tools to enhance the quality and appearance of technical information.
- Meaningful and appropriate graphics supplement descriptive text to clarify and to make more lively the technical information. Here follow some basic rules when using graphics in your documentation:
o Always label your graphics with a caption or a title. Use a different text from the body of your document.
o Illustrate significant concepts.
o Avoid illustrating what is already visible.
o Choose graphics that complement the text.
- Logical, systematic, and consistent use of icons and symbols help users feel comfortable and confident while using your information. For example, you can use iconic images on buttons to represent program tools.
- Be sure to use legible textual elements. Here are some principles to keep in mind:
o Do not use more than three different typefaces per document. A good combination is to use a sans serif typeface for headings and a serif typeface for body text.
o For body text, 10- or 11-point type is the most common. Captions and labels for pictures and figures can be the same size as the body text; however, they may be italicized, bolded, or both.
o Use larger type sizes for headings. If you are using several different levels of headings, make them different sizes to provide your readers with quick clues to find specific heading levels.
o Ensure that the contrast between text and background is adequate.
In sum, these are just a few useful and good ways to produce well-organized technical information, as well as, to provide readers with the right tools to find the answers they are looking for simply and fast, and not to feel lost when they need to use your documentation.
Bibliography
Hargis, Gretchen et al. Developing Quality Technical Information: A Handbook for Writers and Editors. New Jersey: IBM Press, 2004.
