This guest post was written by Cheryl Landes, a technical communications consultant, findability expert, and certified MadCap Advanced Developer (MAD) for MadCap Flare. She has contributed chapters on findability to The Language of Content Strategy and The Language of Technical Communication, both published by XML Press.
Whether we’re finishing job-related tasks or making buying decisions, finding the information we need to successfully answer our questions is critical. Often we struggle during this journey and quickly become frustrated because we either discover only bits and pieces of the information we need or nothing at all.
An indexing tool helps ease this pain. From a business perspective, well-written indexes increase a product’s value and reduce costs because:
- Customers are more satisfied with the product due to seamless information retrieval in order to use it effectively.
- Sales from referrals and repeat buyers increase.
- Customer or technical support calls decrease, which reduce costs.
An indexer is a user’s advocate. The indexer always keeps the users in mind by thinking about how they might look up information in the content. To accomplish this, an indexer provides as many options as possible for users to find the same information in the content.
So, you might wonder, why not just look up the information in the table of contents? It’s because the table of contents and a document index have different roles in the content. Learn more about how to improve your technical documentation through document indexing below.
The difference between a table of contents and index
A table of contents is a list of headings and subheadings in the content. These headings and subheadings usually do not contain the terms that we are seeking, and if they do, the information might be more general. In contrast, an index contains specific terms pulled from the discussions in the content that lead us directly to those relevant documents.
When done correctly, document indexes provide alternative points of entry for the same terms in the form of synonyms. Indexes also consolidate important topics in the book so we can find all relevant documents organized in one place. This organization is not always obvious in the table of contents.1
When you can start working on the index
When you’re indexing traditional printed or paper documents, the indexing takes place after the content is finalized, but in MadCap Flare, topics can be indexed as they’re finalized. So, one person might be working on topics in one Flare project while another person is working in another Flare project, and once the paper based documents are finished, the projects can be imported into a master project.
If multiple people are indexing documents in separate Flare projects, it’s important to have a style guide so the index entries (or keywords, the term used in Flare) are consistent throughout the content.
Preparation for creating an index
As with any type of content creation, it’s important to plan before you start document indexing.
- Know your audience.
- Find out the limitations on file formats, page length, or number of entries. The typical length for a printed index in technical documentation is seven percent of the total pages. For online content, there’s no limit.
- Know your company’s style requirements. If your company doesn’t have a style guide for indexes, create one.
What to include and not include in an index
For technical content, always include these items in the index:
- Proper nouns
- Concepts and procedures
- Glossaries
- Acronyms, abbreviations, and symbols
- Fields, buttons, windows, and other product features
- Restrictions, such as warnings and cautions
- Notes, tables, charts, and graphics–only when important to the subject
- Tasks, such as delete, copy, save, or build
- Parameters, variables, and other features of the code if indexing APIs or other content for developers
Do not include these items in the index:
- Cover pages
- Forewords, prefaces, and tables of contents
- Lists of tables and figures
- Bibliographies
- Footnotes, when used as references only
- Subjects that would cover the entire document type (For example, don’t use networks as an entry if your document is about networks.)
The indexing process
Those unfamiliar with indexing assume the terms are pulled from the content automatically and compiled into an index. If this were the case, then the index would be a list of words that direct users to information where the terms are only mentioned but no meaningful context exists.
That’s why only a human can create a thorough, accurate index field that is usable by the target audience. To determine which information will be helpful, an indexer reads the content and analyzes it to develop the terms found in the index. Throughout the indexing process, the indexer anticipates the audience’s needs for using the index by thinking about:
- Which subjects are important?
- Which subjects are not important?
- Which terms will they use to look up the information? Users may not use the terms in the documentation, so including synonyms as cross-references (example: cats. See felines, or remove. See delete) will direct them to the correct location.
Why not just rely on search?
Search engines look at the keywords, titles, links, headings and subheadings, and other content on a page to determine whether the page is a match for the terms entered in the search bar. In other words, it makes a best guess on whether the results it delivers is the information a user is looking for. Search engines also base their results on the popularity of sites from click-throughs. Lately, I’ve noticed on Google and Microsoft Edge that the search results can also capture paid advertisers. For example, recently I was looking for a specific hotel in Anchorage, and although I entered the name of the hotel, followed by “Anchorage,” the search results listed three hotel booking sites at the top of the list. I found the hotel’s direct website halfway down the list.
If you aren’t producing printed documentation but you use Flare's technical documentation software, adding keywords to your content will improve your search results. And if your company decides to output to PDF or another print format, the keywords will be there so you can generate an index in your output.
Footnotes
1 Landes, Cheryl. “Taming the information scavenger hunt.” Communicator, Spring 2015, page 43. Article available at http://tabbycatco.com/wp-content/uploads/2015/06/Taming-the-information-scavenger-hunt.pdf.
Resources
American Society for Indexing – The “About Indexing” page has FAQs about indexing and other information about the craft. This page does not focus on technical indexing, but the concepts apply to any type of indexing. https://www.asindexing.org/about-indexing/
Franklin, Curt. “How Internet Search Engines Work.” Retrieved December 28, 2022, from https://computer.howstuffworks.com/internet/basics/search-engine.htm.
Indexing Society of Canada – The “Resources” page has information ranging from indexing practices and trends to courses in indexing. https://indexers.ca/resources/
Mulvany, Nancy. Indexing Books, Second Edition. University of Chicago Press, 2005. This book is still considered the authority in the craft. https://press.uchicago.edu/ucp/books/book/chicago/I/bo3625262.html
The Chicago Manual of Style has a chapter on indexing. This style guide is available in print or by subscription online. https://www.bibliovault.org/BV.landing.epl?ISBN=9780226287058
The Microsoft Style Guide no longer has a section on indexing, but it has information on writing effective keywords for search. You can access this guide for free. https://learn.microsoft.com/en-us/style-guide/search-writing