Indexing Single-Source Documents

By Kurt Ament, infotektur

Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

• Introduction
• Assembling Indexes
• Building Index Entries
• Building Indexing Guidelines
• Conclusion

Introduction    

Single sourcing is a documentation method that enables you to reuse the information that you develop. You build modular information, then assemble that information into different formats, such as printed manuals, online Help, even web sites. Reusing information saves you time and money because it eliminates duplicate work.

Single sourcing changes the way you develop information. And it changes the way you index that information. To be reusable, information must be usable "anywhere, anytime, anyhow." In the same way that you develop modular information for reuse in different documents, you build modular index entries for reuse in different indexes. To ensure that these entries mesh rather than clash, you need indexing standards. Ultimately, single sourcing forces you to integrate indexing into your information development process.

Assembling Indexes    

If you develop single-source documents with an authoring tool that allows you to add index markers to content modules, the index markers travel with the modules as you assemble them into different documents and convert them into different formats. By embedding index markers in modular documents, you can generate document indexes, which you can then convert to different formats.

Although some companies manage their single-source content with content management systems, others decide to test the single sourcing method on small projects first before investing in content management systems. Many use existing (legacy) publishing technologies to convert print-based documents to online Help.

1. Generating Print Indexes

In a legacy publishing environment, you can develop single-source documents with a print-based authoring tool, such as Adobe FrameMaker. You assemble the single-source documents into books, then generate book indexes from index markers in the source documents.

Generating book indexes in FrameMaker

2. Converting Print Indexes

Once you have developed a single-source book and index, you can convert it to a specific online Help format with a conversion tool. Quadralay WebWorks Publisher is one tool used to convert FrameMaker books to various online Help formats.

Converting FrameMaker books to online Help in WebWorks Publisher

3. Testing Online Indexes

When you have converted a single-source book to an online Help format, such as Microsoft HTML Help or Oracle Help, you can test it in that online format.

Testing an Oracle Help index

Building Index Entries    

To build reusable index entries, you index standalone content by module type.

There are two basic types of content modules:

• Steps (procedures and processes)
• Topics (concepts and references)

Because you index steps and topics differently, your first task as an indexer is to identify which content modules are steps and which are topics.

Indexing Steps

Steps explain how to perform tasks sequentially:

• Procedures (active)
  Procedures are step-by-step instructions that explain how to perform specific tasks. They explain what users do (imperative), not what someone or something does (declarative).

• Processes (passive)
  Processes explain how a task is performed. They explain what someone or something does (declarative), not what users do (imperative).

When indexing procedures and processes, build two index entries. Begin one entry with a verb (for example, "printing document"). Begin the other entry with a noun (for example, "document, printing"). By "double posting" each procedure and process by verb and noun, you help ensure that users find the information they need, no matter where they look for it. This approach enables you to develop consistent and predictable index entries, which increase index usability and reusability.

Once you begin indexing steps, you will notice that clearly and consistently labeled procedures and processes are easier to index. Consistent heading syntax makes it easier for you to identify modules by type, then index them accordingly. Even more important, consistent headings help users to find the procedures or processes they need quickly.

Indexing Topics

Topics are texts that explain who, what, when, where, or why:

• Concepts (general)
  Conceptual topics answer general questions (for example, what a product is or what it does). They are normally formatted as paragraphs, and can include figures and tables.

• References (specific)
  Reference topics answer specific questions (for example, describe product components and technologies). They are normally formatted as definition lists.

In the same way that you can build index entries for procedures and processes that mirror the verb-driven syntax of their headings, you can build index entries for conceptual and reference topics that mirror the noun-driven syntax of their headings. When indexing conceptual and reference topics, index by noun only.

If you follow a consistent heading syntax for topics (for example, beginning headings with keywords that indicate topic types followed by nouns), you can mirror this syntax in your index entries (for example, reversing the syntax, beginning entries with nouns followed by keywords).

Building Indexing Guidelines    

Consistent index entries are not accidental, particularly in a single sourcing environment. For modular content and index entries from multiple authors to merger seamlessly rather than clash when assembled into different documents, you need to establish content and format guidelines for indexing.

Rather than setting up complicated ivory tower indexing guidelines that work in theory, set up simple consensual guidelines that work in practice. Consensus is not democracy. Consensus forces teams to sink or swim together. Make sure that the entire team agrees with guidelines before you finalize them. If you try to impose indexing guidelines from above, you will meet resistance in the trenches. Better to publish realistic guidelines that everyone follows than to publish ideal guidelines that no one follows.

Content Guidelines

Build content guidelines to control the "granularity" of your shared index entries:

• Modules
  Build guidelines for indexing modules by type. At a bare minimum, decide how you want to index step-by-step procedures and processes, as well as conceptual and reference topics.

• Submodules
  When first building guidelines, you can safely ignore examples, figures, tables, and notes, which are actually secondary modules that are components of primary modules (steps and topics).

• Master indexes
  If you are developing master indexes or master helpsets, you may need to include product and component names in index entries so as not to confuse users. Unfortunately, such entries look strange in individual indexes. Ultimately, you need to decide whether to develop index entries to be used in individual indexes and helpsets, or whether to develop index entries to be used in master indexes and helpsets. Doing both is almost impossible.

• Conditional text
  When setting up conditional text, you need to decide what types of content should appear in what types of documents. By showing or hiding sections set to conditional text, you show or hide their index entries when generating index documents. Set up simple conditional text styles (for example, PrintOnly and HelpOnly) that all authors on your team can understand.

Always include negative and positive examples from real projects to illustrate your guidelines. When setting up examples, be very precise. As anyone who has developed style guides know, authors tend to follow examples literally.

Format Guidelines

Build guidelines for print and online formats:

• Sort order
  Different publishing tools sort index entries differently. For example, some tools sort character-by-character, while others sort word-by-word. Many online Help systems do not allow you to override the sort order of index entries. This can wreck havoc on indexes authored in more sophisticated print-based tools (for example, placing all entries beginning with quotation marks at the very top of the index, no matter what their first alphabetical character is). Before building index guidelines, make sure you understand how your entries will sort in different formats.

• Nesting levels
  Print-based publishing tools usually allow you to build up to five levels of index entries (although three is more than adequate). But some online Help systems allow only two index levels. For example, when converting a three-level print index to a two-level online format, you can program workarounds, such as concatenating second- and third-level entries, then separating them with colons. Before building indexing guidelines, make sure you understand how your various tools handle index levels.

• Cross-references
  Although "see" and "see also" references can be extremely helpful to users in print documents, they can actually hinder users in some online Help systems. For example, "see" and "see also" references are not hyperlinked in FrameMaker. If they are then converted to online Help, they appear in the online index but do nothing when clicked, which can frustrate users. Before building indexing guidelines, make sure you understand how "see" and "see also" references function in your online Help systems.

• Page numbers
  Avoid serial page numbers in your source indexes. Serial page numbers can indicate redundancy, inconsistency, or mislabeling in your source documents. They can also create serious usability problems when indexes are converted to online Help formats, which never include page numbers in index entries. When building indexing guidelines, instruct authors to break entries with serial page numbers into more specific subentries with single page numbers.

People have been exposed to online media for only a few decades. As a result, online Help systems are not nearly as fault-tolerant as printed manuals. When building indexing standards, focus on online Help. If an index works well online, it will work even better on paper. Investigate how each of your publishing tools formats index entries, then plan for the "worst case" scenario: online Help.

Conclusion    

Single sourcing is a method of systematically reusing content. To be reusable, content must be usable in multiple documents and formats. In the same way that you develop modular content to reuse in different documents, you can build modular index entries to reused in different indexes. To ensure that these entries mesh rather than clash, you need indexing standards. If you build consensual indexing standards based on real projects, you will increase the usability your indexes exponentially.

Kurt Ament (www.infotektur.com) is an information architect with extensive experience in print and online publishing. For over a decade, he has developed end-user documentation, corporate style guides, and document conversion templates for companies such as HP, Hughes, Symantec, and Xerox. The WebWorks Publisher templates he developed to convert single-source FrameMaker+SGML books to HTML- and Java-based online Help systems are now used by clients in the U.S., Europe, and Asia. A senior member of STC, Kurt is the author of Single Sourcing: Building Modular Documentation and Indexing: A Nuts-and-Bolts Guide for Technical Writers. This article is based on a presentation he made at the WinWriters Online Help Conference Europe 2003 in London.