If a document contains the information that a reader needs, but if the reader cannot find that information, then the document is useless. Worse than useless, it’s a hindrance. If I know that some information is not available, I won’t waste my time looking for it. However, if I think the information is available, and if I can’t find it after a period of fruitless searching, all I will have achieved is frustration.
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.
Indexes are as important to your documentation as your documentation is to the product. Just as it would be difficult, if not impossible, for people to use your product without any documentation, it is equally difficult for people to use documentation without a good index.
Indexing the Web is not a simple task, and what is evolving to meet the informational needs of Web users are three different kinds of indexing: a back-of-the-book style of hard-coded index links within a Web site, subject trees of reviewed sites, and search engines. Some organizations are seeing that including indexes on their web sites is just as important as including indexes in books and online manuals. We've seen some good and some bad, some computer-generated, some obviously not constructed by professional indexers, and some professionally prepared. In any case, all site owners should be commended for recognizing the need for an index.
Because user tasks form the foundation of modern 'task-based' documentation, tasks should be well-represented in the index. We need to create index headings for both the broad objectives of the user (e.g., balancing a cheque book), and the specific actions required by the application (e.g., opening a file).
One of our favorite cliches is that you can't use the printed book as a model for online information. Web-based information, which is following the same evolutionary progress as online help systems, has inherited this 'books are bad' philosophy. However, any statement we've begun to take for granted bears some re-examination, because unquestioningly accepting dogma undermines our efforts to improve communication.
Indexing a document is an art in itself. Since Adobe FrameMaker is the program of choice for most companies producing technical documentation, it is worth while to find out how to create an index in FrameMaker.
Microsoft Word assists you in creating an embedded index. While Microsoft Word makes it easy to enter individual index entries, much effort is still required to create page ranges and to edit the final index.
The page number provides an intuitive context. Embedded indexing tools suffer because this context is transparent to authors. Further challenges arise from the low design priority awarded to embedding indexing tools of several applications. Hypertext-based indexing, such as on the World Wide Web, is an extreme case with difficulties ranging from a huge scope with negligible natural content, to a programming language that provides no straightforward technique for indentation.
This workshop presents a step-by-step methodology for producing thorough, usable indexes for technical documents. The methodology consists of these four steps: 1) Creating entries based on the material; 2) Creating entries based on users' questions; 3) Adding synonyms; and 4) Cross-referencing related entries. The workshop also includes hands-on exercises which illustrate the methodology and give participants a chance to practice using it.
Users feel confident if they can find the information they need easily. Indexes are one device users have for finding information. If an index is complete and consistent, users are given the confidence they need.
There is widespread confusion, even in the technical communication field, about the real nature and purpose of an index. This is unsettling, because an understanding of the role of the index is vital to those who create information products and also to those using the information products. Consequently, it is important for technical communicators to familiarize themselves with some basic facts about indexing and to dispel the common misconceptions about the purpose, use, and creation of an index.
What is an index? Meeting user expectations.
RoboHelp HTML, from eHelp Corporation, is a powerful software tool for creating online Help systems. Included within RoboHelp HTML is the ability to develop indexes for online Help projects.
Recently Greg Thompson, Sheila Loring, and Stephanie Mills had a discussion about interns and internships in technical communication. Greg and Sheila had experience directing interns, and Stephanie had experience working as an intern. The conversation explored these two perspectives on internships.
Da tre anni Italianistica Online seleziona e recensisce le risorse internet per gli studi italianistici, fornendo un servizio gratuito, uno spazio di informazione e approfondimento sulla cultura italiana in rete, cercando di rispecchiare il cambiamento in atto, sollecitando a ragionare e discutere sulle opportunità offerte da Internet per gli studi italianistici. Particolare risalto ha avuto e continua ad avere il Dossier sul libro elettronico e l'editoria digitale umanistica in Italia (in rete dal 2001), insieme alla conferenza telematica sul medesimo tema, che per la prima volta in maniera organica fornisce documenti e spunti di riflessione sui nuovi scenari dell'editoria digitale. Un progetto originale di rilievo è la Bibliotheca Umbra, antologia digitale telematica dei documenti di lingua e dei testi di letteratura prodotti nella regione umbra dalle Origini al Novecento.
Indexing often waits until a document is nearly finalized or “camera ready.” This is because indexers often need to have the final page numbers or the original document files before starting. But, starting the index so late means extending the publication process by several days or even weeks. And the time available to create a quality index — likely the most well-used part of any business or technical publication — can be severely squeezed.
Online indexes have the same logical structure as print indexes with main headings and usually subheadings. Some online indexes can also be searched electronically. A search request in Yahoo! returns a list of online category headings. Online indexes, like their print cousins, are true 'searchable structures,' not simply concordance lists of terms appearing in the text.
The age-old art of indexing will continue to be essential for the quick and accurate retrieval of information, no matter what the medium might be. Advances in technology will not replace the need for well-prepared indexes, only how indexes are presented. Information on indexing for newer forms of communication is scattered and not fully developed. This session will bring together what is known to give attendees a better understanding of the trends, issues, concerns, and requirements that are involved in “newage” indexing.
Turn to the index in the back of any O'Reilly book published in the last five years and chances are you're looking at the handiwork of O'Reilly's resident indexing guru, Seth Maislin. Though indexes are the most frequently fingered section of any computer book, they remain the one element most taken for granted. Those ostensibly logical, orderly columns of subject-page references belie the complexity of indexing. The craft of indexing involves much more than the mere alphabetization of a book's key words. It requires something that is at once science and art form, the product of someone painstakingly fleshing out a book's information design while copiously accounting for nuances of language and word associations. You might say an index is like a fingerprint: intricate, revealing, utterly unique.
Effective documentation is built around the work environment of the user. The index, too, should relate to the work the user performs. As in the body of your documentation, topics in your index should consist primarily of objects, tasks and concepts from the world of the user
Indexing is a mystery to many people who are writing and printing materials. An index is an offering to your readers - a way in to your material, a subject finder and a detailed guide to the contents of your piece. Indexing itself is a precise art, with not much real mystery when you get into it deeply.