The Technical Editors' Eyrie Newsletter

Issue 42, 1 December 2000

ISSN 1442-8652

Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com

In this issue...

Feature article: Editing the contents page and index (extract from Editing Online Help)
Web communication information for editors and others
Office 2000 HTML filter
Listserv/support group for editors at Editors Association of Canada
Web sites for copyeditors
Now available: Editing Online Help by Jean Hollis Weber
Subscription information

Feature article: Editing the contents page and index (extract from Editing Online Help)

Readers use a help system's contents page or index in several situations:

When the help system always opens at the contents page, and does not have a relevant help topic linked to each application dialog, window, or page.
When they wish to look up information not associated with the application dialog that is currently open.
When the help system opens to a "what do you want help with" dialog that provides sample choices and a text-entry box, if they find the choices irrelevant to their question.

A contents page provides readers with a hierarchical view of the content of your help system. When readers select a topic listed in the table of contents, they are taken directly to the information they are looking for. You can organize the contents page by subject or by category, and you can include a topic under more than one heading, so readers have more than one way to find it.

Some readers prefer to use the Search function instead of the index. By using Search, they can locate every topic that contains a particular word. This may assist them in locating poorly-indexed topics, but may also give them a long list of irrelevant topics to wade through. Search is also limited to words that actually appear in the help topics, and thus does not find synonyms.

An index contains keywords that the writer specifies. It can therefore contain terms for beginners and advanced users, synonyms for terms, terms that describe topics generally, and terms that describe topics specifically. A well-developed index can provide readers with many different ways to find topics, in contrast to a contents page which usually provides only one way to find each topic.

A well-designed contents page and index will help many readers locate the information they require. If only a few attempts at using these retrieval aids don't help, readers will often reject the help as useless and not look at it again.

Of course, a great contents page and index are not enough -- you also need to make sure that the topics contain the necessary information.

Editing a table of contents

The author should have created a meaningful contents page for the help project.

Topic titles and the structure of the contents page need to be logical from the readers' point of view, which may be quite different from the developers' point of view. For example, developers might group topics by program functions, which do not always correspond with users' tasks.

A help contents page should be similar to the structure of a table of contents in a printed book, but the best sequence of topics may be different. The best sequence varies with the audience. You might begin with tasks usually done first and progress in a chronological order, or begin with common tasks and progress to less-common ones, or begin with easy tasks and progress to more difficult or complicated ones. Many help systems group topics into Getting Started, Procedures, and Reference, or other logical groupings for different needs and skill levels.

You can organize topics using icons that identify main topics and subtopics. For example, in WinHelp, if you use the default icons, book icons represent headings and page icons represent topics. HTML Help provides a folder icon for main topics and a page icon for subtopics. You can change the default icons or create your own contents icons.

Double-clicking a folder or book icon displays the subentries under that heading. Subentries can be other book icons or page icons. Double-clicking a page icon displays a topic.

The contents page can be displayed in various ways, but the basic structure of the table of contents is the same in each case.

Quick diagnostics

To determine whether a contents page has major problems:

Examine the structure of the contents and the headings in it.
Take some sample questions from your task and question list and try to find the answers, using the table of contents.

Note: A contents page does not need to include every topic in the help system. For example, some topics (including pop-up topics) may make sense only when displayed from another topic. However, you do need to make sure that the contents page includes at least one topic for each subject that a reader might want to look up; that topic can then link to related topics.

Editing indexes

Writers need to put as much, or more, care into creating an index for online help as they would put into creating an index for printed documentation. They should use the same general principles for creating index entries (called keywords in most help-authoring systems) for online help as for printed documents.

A full treatment of indexing, and the selection of appropriate keywords, is beyond the scope of this book. Look in Appendix C, For more information, for some suggested books on indexing. Chapter 9, "Creating the index," in Boggan et al. (1999) is particularly good.

All the usual book-indexing questions apply to online help. In addition, you need to look for problems created by the help authoring tool, which can create index keywords automatically from topic titles. Although some of these will be useful, others will be noise, and many valuable index entries (such as second-level entries) won't be created automatically. Help authoring tools provide ways to assist you and the writer in creating new entries and editing the resulting index.

If you are creating an HTML-based help system using software that does not provide a built-in indexing function, you might consider using a tool such as HTML Indexer; see Appendix B, Choosing help types and tools.

Quick diagnostics

Some indexes have major structural and other problems; others need relatively minor tweaking and copy-editing to improve them.

To determine whether an index has major problems:

Take some sample questions from your task and question list and try to find the answers, using the index.
Do some random lookups in the help, to see whether the term or topic is in the index.

If several random selections are not in the index, this suggests that a lot more work needs to be done. Now you need to determine what the major problems are and what should be done to fix them.

Web communication information for editors and others

George Hayhoe george@ghayhoe.com, Editor of the STC's journal Technical Communication, reported on the Technical Writers' list,

"The quicklist versions of the heuristics for Web communication published in the August 2000 issue of Technical Communication are now available to the general public at the Technical Communication Online site: http://www.techcomm-online.org/shared/special_col/quicklists/menu.html

"The quicklists are derived from five sets of heuristics on designing personas, Web navigation, designing comprehensible Web pages, displaying information on the Web, and collecting Web data to understand and interact with users. A summary of the introduction to the special issue is also included.

"These heuristics are intended to help Web designers and developers consider crucial communicative aspects of Web site design.

"No registration is required to access the quicklist versions of the heuristics.

"Members of the Society for Technical Communication may access the full versions of the articles at http://www.techcomm-online.org/issues/v47n3/toc.html

"All content at the site except the most recent four issues is available to registered guests. To register as a member or guest, see http://www.techcomm-online.org "

My comment: These quicklists may be useful when an editor is negotiating with clients, designers, writers, and others regarding usability and other issues, particularly when you need an authoritative source to back up your recommendations.

Office 2000 HTML filter

John Daigle daigle@hypertexas.com wrote to HATT@egroups.com about an Office 2000 HTML Filter:

"The URL for the HTML Filter 2.0 for Word 2000 is http://office.microsoft.com/downloads/2000/Msohtmf2.aspx

Editor's note: I changed the URL from the original one given by John to the current one in November 2001.

"This is a crucial utility for anyone having to convert Word 2000 docs into HTML. In addition to adding a new menu item ( File | Export to | Compact HTML), it takes out the XML code bloat. Originally this [XML code] was meant to allow for company intranet users to post a Word.DOC as Word.HTM that would "look" exactly like the .DOC format. While this works amazingly well, the resulting code bloat makes it worthless in terms of bandwidth hogging. Also, other HTML editors or [help authoring tools] will "choke" if you try to import this XML-ized document.

"With slightly more trouble (opening a DOS box) there are some good command line switches that can control just how "pure" you want the output to be with regard to CSS, etc. Ray Dembek on the old Winhlp-L reported his test results with the filter: 'When the filter is run from the DOS prompt as filter -a -b -c -l -m -r -s input.htm output.htm the output has almost no extraneous markup in my brief testing. The files created via Save as Compact HTML in Word have much more useless information in them.'

"I found this to be a great tip and use it often."

My comment: I haven't tried this yet, because I'm still using Word 97, but if it works as well as John says, I'm sure it will be a valuable addition to my HTML editing toolkit.

Listserv/support group for editors at Editors Association of Canada

In issue 39, someone wrote asking for "any kind of listserv/ support group for editors." Two suggestions (copyediting-l and edline) were given in issue 40. Someone else has offered this suggestion:

The Editors Association of Canada (EAC), at http://www.editors.ca. Once you've joined the Association you can participate in their discussion list.

Web sites for copyeditors

In addition to the Electric Editors and EDline, mentioned in issue 40, here are some Web sites gleaned from various sources, but not checked by me.

http://www.copyeditor.com/ (June 2003 note: site not found.)

Garbl's Writing Resources Online (December 2003 note: site not found.)

Common Errors in English http://www.wsu.edu/~brians/errors/errors.html

Web of Online Dictionaries - appears to be gone

Web of Online Grammars http://www.yourdictionary.com/grammars.html

The Slot: A Spot for Copy Editors (includes The Curmudgeon's Style Guide) http://www.theslot.com/

Now available - Editing Online Help

by Jean Hollis Weber
155 pages
ISBN 0-9578419-0-6
Published October 12, 2000

For students, writers, and editors who are developing online help for computer software, and for their managers and clients.

Supplements tool-specific instruction by presenting the basics of help content development, regardless of the operating system running the application, the type of help being produced, or the tools used to produce it.

Formats
Available in PDF, WinHelp 4, HTML Help, and browser-independent HTML (with and without frames).

Downloaded copy US$8.00, A$15.00
CD-ROM US$15.00, A$25.00 (includes postage)
Printed copy (includes CD-ROM, postage) US$30.00, A$40.00
Each choice includes all of the versions of the book.

Table of contents and instructions on how to get copies are here: http://www.jeanweber.com/books/olhbk.htm

Payment instructions are here: http://www.jeanweber.com/books/payme.htm

You may forward this newsletter (in whole or in part) to friends and colleagues, as long as you retain this copyright and subscription information, and do not charge any fee.

Subscription information

This newsletter is no longer being published.

Privacy statement

I do not sell, rent, or give my mailing list to anyone.

Articles © Copyright by their authors.
© Copyright Jean Hollis Weber, Technical Editing Consultant
WeberWoman's Wrevenge, Airlie Beach, Qld., Australia, jean@jeanweber.com
ABN 18 005 740 467

Last updated 1 June 2003