Context-sensitive help systems often need redundant placement of information. This ensures that the information is seen by visitors who enter and move unpredictably through the system. Redundant placements take the form of descriptions, explanations, warnings, and the like that amplify other subjects. In software documentation, for example, some candidate subjects include the purposes of screens and tabs, the effects of selected options and significant functions such as Delete, and reminders of required access permissions and prerequisite steps or conditions. You can save development time and promote consistency by cataloging information so that it can be inserted wherever needed using your authoring software's copy and paste functions.
An index is an important navigation device in documentation, especially in print. It helps users to quickly find key terms, concepts, functions, and instructions. In this post, I share my best advice about building an index.
Indexing a software manual is not very different from indexing any other manual. As a simple rule, make sure you index all of the software features: screens, windows, fields, options and commands. Index system errors and warnings if applicable. Use cross-references to direct the reader to the term used in the manual if it differs from the generally-used jargon.
Giving your readers a quality index takes a careful consideration of the tools, time frame, workgroup process, and results you plan for the piece. Planning for the index must start at the beginning of the project, in order to have the essential processes clear to all involved As the documentation process itself becomes more complex, trying to meet different needs in different environments, so does indexing. As print-based documentation moves to online, the index or keywords becomes critical to your users. In this session, participants will learn what kinds of tools are available for indexing, the benefits of each, what the stages of indexing are, and the amount of time to allow for each.
Creating an index for a technical manual requires an understanding of what constitutes a high-quality index and the indexing methodology. This workshop presents the methodologies and steps necessary to create such an index.