Indexing

A Nuts-and-Bolts Guide for Technical Writers

Kurt Ament

• Publisher: William Andrew
• Year: 2001
• Print ISBN: 9780815514817
• eBook ISBN: 9780815518044
• Topic: Technology & Engineering
• Subtopic: Technology & Engineering Research & Skills
• Index: Technology & Engineering

Indexing: A Practical Guide for Technical Writers is a nuts-and-bolts guide to indexing. It explains in plain language and by example exactly how to index any type of print or online publication quickly, easily, and effectively. The sequential indexing method presented in the book has been battle-tested in high pressure publishing organizations in a variety of high-tech industries over the space of a decade. Because it is based on real-world success, this indexing method is bulletproof. Users of this guide will succeed as an indexer. Unlike other books on the subject, this book is focused on readers, not the subject itself. The book speaks directly to highly practical and often anti-academic technical writers who demand usability, reusability, and reliability. It is geared to people with ""Keep It Simple, Stupid"" signs on their cubicle walls.Proven end-user documentation techniques are employed to present proven indexing methods to readers who themselves develop end-user documentation for a living. They have zero tolerance for academic white papers on indexing. So, the book delivers the hard facts.

CHAPTER 1

About indexing

Indexing is not rocket science. Indexing is a relatively simple task that can be learned quickly and painlessly. All you need to start indexing successfully is a practical plan of attack. This chapter outlines a practical indexing method that has proven itself in real-world technical publishing environments. If you follow this method, you will succeed as an indexer.

Anyone can index

Indexing is a task performed every day by perfectly normal people like you.

Indexers are made, not born

In the technical publishing field, indexers are technical writers and editors who, at some point in their careers, have an indexing assignment thrust upon them. Typically the orders come from someone further up the corporate food chain. The person giving the orders knows indexes are important but does not have a clear idea what an index is, let alone how to build one. The person receiving the orders is left alone in the dark. And so begins the long, lonely march into the unknown.

Indexing does not have to be painful

As a novice indexer, you don’t need to reinvent the wheel or blaze new trails. Many indexers have indexed before you. These pioneers have learned, often the hard way, what works and what doesn’t. In the process, they have laid the groundwork for your success as an indexer.

Nothing succeeds like success

To succeed as an indexer, simply follow the indexing method used by successful indexers. The most successful indexing method used by professional indexers is quick, easy, and foolproof. This method is called sequential indexing.

Sequential indexing

Sequential indexing is a proven method for creating indexes. This indexing method separates index creation (content) from index editing (format). By separating content from format, the sequential method breaks an otherwise overwhelming task into bite-sized tasks anyone can perform under real-world conditions. By performing these simple tasks one step at a time, you will build accurate and usable indexes quickly and easily.

TIP

Although sequential indexing has its origin in printed software guides, you can easily adapt the method to any medium (for example, online help systems or websites).

Separating content from format

Like all successful documentation methods, sequential indexing separates content from format:

1. Create index content

    In the early stages of developing your index, you focus exclusively on the content of the document you are indexing. You index distinct types of information, type by type, without regard to the format of the index itself. By ignoring the format of the index, you create factually accurate index entries with minimal effort.

2. Edit index format

    Once you have created your index entries, you focus exclusively on the format of the index. When editing the format of the index, you concentrate on usability alone. That is, you tailor the format of the index to the specific needs of your users. This exclusive focus on usability is the best method for transforming raw content into a truly usable index.

Keeping your sanity

Indexing one step at a time breaks your work into easily manageable tasks. This task-driven approach insulates you from a chronic problem in most work environments: chaos. Sequential indexing assumes you will be interrupted frequently. While indexing, you will be interrupted by telephone calls, emergency meetings, even computer failure. By focusing on simple tasks, you will recover from these interruptions with very little effort.

Usable indexes increase profits

Sequential indexing does more than make your job easier. It enables you to create usable indexes. Usable indexes improve product documentation. Usable product documentation improves products. And usable products sell.

Usable indexes improve documentation

An index is a documentation tool that saves time and energy. This tool enables users to find information in documentation quickly and easily. Rapid information retrieval is critical to the success of product documentation. Unlike classical literature or pulp fiction, product documentation is almost always scanned, not read cover to cover. In fact, users often turn to product documentation as a last resort, particularly when something has gone horribly wrong with the product they are using. The less time and energy it takes users to find the information they need, the more usable the documentation.

The more usable the documentation, the easier it is to index. Well-structured documents are easy to index, and poorly structured documents are difficult to index. If a document is difficult to index, the document most likely has structural problems. That is the bad news. The good news is that the process of indexing uncovers these otherwise hidden structural problems. For this reason, professional editors routinely use the process of indexing to diagnose and correct structural problems within product documentation.

Usable documentation improves products

In the same way that usable documentation is easy to index, usable products are easy to document. The converse is also true: unusable products are difficult to document. If a product is difficult to document, it is very likely that the product has structural problems. Many of these structural problems are uncovered during the documentation process itself. For this reason, product development teams routinely use the process of documentation to diagnose and correct structural problems within products. In other words, documentation serves as product quality assurance.

The dual role of product documentation is underlined by an overworked joke in the software industry. Software engineers often refer to program errors, or bugs, as “undocumented features.” This dark humor is not shared by product users. As the “first users” of the products they document, technical writers routinely uncover product errors. In well-functioning product development groups, errors uncovered by technical writers are corrected by product developers. Obviously, these corrections make products easier to use.

Usable products sell

Products that are easy to use attract and retain customers. This fact is indisputable. In a free market, customer loyalty depends on usable products. Usable products depend on usable product documentation, which in turn depends on usable indexes. The better the index, the better the documentation. The better the documentation, the better the product. The better the product, the better the sales. In other words, usable indexes contribute directly to product sales.

CHAPTER 2

Star...

Table of contents

• Cover
• Title page
• Table of Contents
• Copyright
• PREFACE: About this guide
• Chapter 1: About indexing
• Chapter 2: Start indexing
• Chapter 3: Indexing guidelines
• INDEX