Indexing Single-Source Documents
By Kurt Ament, infotektur
Click a link below to jump to a particular section; click any "
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.
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
To build reusable index entries, you index standalone content by module type.
There are two basic types of content modules:
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.
Steps explain how to perform tasks sequentially:
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.
Topics are texts that explain who, what, when, where, or why:
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).
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.
Build content guidelines to control the "granularity" of your shared index entries:
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.
Build guidelines for print and online formats:
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.
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.