http://tc.eserver.org/authors/Brown,_Fred A bibliography of works by Brown, Fred in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Brown,_Fred http://tc.eserver.org/28574.html http://tc.eserver.org/28574.html Metadata from the world of librarians and database searching is moving to center stage in our everyday lives. And the metadata 'revolution' is coming to us through pictures--those cute, happy, funny shots of kids, parents, neighbors and workmates that we love to share and post on the internet. http://tc.eserver.org/28136.html http://tc.eserver.org/28136.html When users find the answers they are looking for, the investment in technical documentation gets a chance to pay off. In large volumes of technical information, just finding the answer can be half the battle. Microsoft found that users of its intranet were spending an average of 2.5 hours per day online - 50% of that being searching. This article was written as part of an experimental online workshop with the MITWA (Mentors, Indexers, Technical Writers & Associates) discussion group(http://groups.yahoo.com/group/MITWA/). The article retains the workshop format including learning assignments. http://tc.eserver.org/27884.html http://tc.eserver.org/27884.html The index can often be the most heavily used 'chapter' in any publication and helping the user find an answer is the key to fulfilling the technical document's mission, justifying the effort and expense for its creation. Yet, indexing facilities in open source packages for document creation remains largely unexplored, offering a marvelous opportunity to do it right! This article provides a generic specification (with reasons) to open source developers for creating useful indexing facilities in packages such as OpenOffice and Scribus. It also informs writers about what to look for and what to ask for in any indexing tool. Finally, the article demonstrates the need for software developers to work closely with practitioners and users. http://tc.eserver.org/19943.html http://tc.eserver.org/19943.html Much like the well-known back-of-the-book index, web indexes help users find information using a variety of keywords and gathering similar information under a single topic. Instead of page numbers, web indexes are hypertext-linked directly to the content with in the web site itself. Web indexes work particularly well in sites that have a flat structure with only one or two levels of hierarchy. http://tc.eserver.org/18554.html http://tc.eserver.org/18554.html It is important to alphabetize your index in a consistent manner. Otherwise, your readers may become confused or miss an important entry. There are two basic ways to alphabetize, or sort, an index: word by word; letter by letter. http://tc.eserver.org/18542.html http://tc.eserver.org/18542.html Before publishing your index, you need to ensure that the 'See' and 'See also' cross-references work correctly. The text in each cross-reference must exactly match the text in the index heading it refers to. http://tc.eserver.org/18546.html http://tc.eserver.org/18546.html The DocBook document type definition (DTD) was developed during the 1990s to provide an application independent method for creating computer documentation. Versions of the DocBook DTD have been created for both SGML and XML. You can create an embedded index in DocBook using index elements. http://tc.eserver.org/18552.html http://tc.eserver.org/18552.html Selecting the right type of index can save you both time and money. You create an embedded index by entering index markers directly into your document. You then generate the index from the embedded markers. With a stand-alone index, you create the index as a separate text file using dedicated indexing software. Embedded indexes are used commonly for software documentation while stand-alone indexes are used extensively in book publishing. http://tc.eserver.org/18541.html http://tc.eserver.org/18541.html People think about questions or information in different ways. It’s important for an index to provide multiple ways of locating any given piece of information. http://tc.eserver.org/18555.html http://tc.eserver.org/18555.html Formatting your index attractively can improve readability and help your audience to locate information quickly. The following tips apply to printed indexes. http://tc.eserver.org/18548.html http://tc.eserver.org/18548.html The American Society of Indexers identifies criteria for measuring a great index. An index is not an inverted table of contents, nor is it a simple listing of where certain terms appear in a document. An index consists of a 'compiled list of topics covered in the work, prepared with the reader’s needs in mind.' http://tc.eserver.org/18558.html http://tc.eserver.org/18558.html Indexing in FrameMaker can feel frustrating and time-consuming — especially when under the pressure of a deadline. http://tc.eserver.org/18547.html http://tc.eserver.org/18547.html 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). http://tc.eserver.org/18543.html http://tc.eserver.org/18543.html 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. http://tc.eserver.org/18544.html http://tc.eserver.org/18544.html 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. http://tc.eserver.org/18549.html http://tc.eserver.org/18549.html 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. http://tc.eserver.org/18557.html http://tc.eserver.org/18557.html 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 http://tc.eserver.org/18553.html http://tc.eserver.org/18553.html Before starting to write the index, take some time to absorb the overall gist of what’s being said and how things relate one to another. http://tc.eserver.org/18556.html http://tc.eserver.org/18556.html 'See also' cross-references assist the user to quickly navigate to the right index term. The same principles that apply to 'See also' cross-references apply equally to hypertext linking. 'See also' cross-references are constructed using the following relationships: a broader term to a narrower term, e.g. 'mammals, See also whales'; sailing craft, See also hulls overlapping meaning between two terms, e.g. 'gold, See also money' http://tc.eserver.org/18545.html http://tc.eserver.org/18545.html Subheadings enable your readers to find detailed information quickly. They also give the reader an idea of how deeply a topic is covered. Subheadings provide more detail about the topic stated in the main entry. Effective subheadings represent distinct aspects of a topic. http://tc.eserver.org/18551.html http://tc.eserver.org/18551.html Including synonyms can be one of the most effective ways to improve the usability of an index. Synonyms assist users to navigate easily to the information they are looking for using their own terminology. In an index you use the terms that appear in the text of the document. But, the user may employ different words for the same concepts. This situation can happen when a user is familiar with another environment, for example when an experienced Microsoft Windows user is learning about Linux. The user may also be familiar with common terms while the document may use scientific or other official terminology. Different industries, organizations or product groups can also develop their own specialized vocabularies. http://tc.eserver.org/18550.html http://tc.eserver.org/18550.html Recently on INDEX-L, the indexer’s listserv, there was a thread on quotes about the value of indexing. See the article for some select examples. http://tc.eserver.org/18559.html http://tc.eserver.org/18559.html What indexes can do for you and your end-users. http://tc.eserver.org/18306.html http://tc.eserver.org/18306.html An index pulls together all the references to a topic that are scattered within a publication. If a reference is omitted, the user may assume that particular sub-topic is not discussed. http://tc.eserver.org/14491.html http://tc.eserver.org/14491.html While WebWorks Publisher (WWP) 7.0 can convert FrameMaker indexes into different online formats, getting things to work initially can be a bit of a challenge. Page ranges in index entries result in hyperlinks to both the starting and ending locations. Index hyperlinks don’t always link to the top of a help topic, but often to somewhere in the middle. For Simple HTML and Dynamic HTML, “See” and “See also” references can fail to convert altogether. However, if you do get stuck, Customer Support can help pull you through. http://tc.eserver.org/14489.html http://tc.eserver.org/14489.html FrameMaker provides you with the ability to enter individual index headings using index markers. Once entered, you can automatically generate the index with the correct page numbers. http://tc.eserver.org/14490.html http://tc.eserver.org/14490.html Acronyms and initialisms pepper the workplace conversation in many technical and scientific environments. If you’re new to the organization or industry, the many unknown acronyms can be a real barrier to comprehending anything at all. Published books and technical documentation often spell out the full term when first used and then employ the acronym only. As indexers we need to serve both the “newbies,” who find the acronyms confusing, and the “old hands,” who dream only in acronyms. http://tc.eserver.org/14493.html http://tc.eserver.org/14493.html Handling personal and geographic names can be complicated. Many rules apply to personal names. http://tc.eserver.org/14492.html http://tc.eserver.org/14492.html Many publishers of technical material are now publishing in more than one format, e.g. print, Adobe Acrobat (PDF), HTML, HTML Help and XML. Typically, a master document is first created in a package such as Adobe FrameMaker or Microsoft Word. The master document is then converted into different formats for publishing. Indexes are often the Achilles heel of such a process, because indexes can rarely be converted like regular material. Indexes usually have to be regenerated or recreated within the new format rather than simply converted from an existing file. http://tc.eserver.org/10810.html http://tc.eserver.org/10810.html Like any well-written document, an index needs to be edited. Editing ensures consistency, clarity, completeness and accuracy. And an effective index contributes substantially to the usability of a document.