Issue 42, 1 December 2000
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
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.
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.
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.
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.
George Hayhoe email@example.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.
John Daigle firstname.lastname@example.org 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.
The Editors Association of Canada (EAC), at http://www.editors.ca. Once you've joined the Association you can participate in their discussion list.
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/
by Jean Hollis Weber
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.
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
© Copyright 2000, Jean Hollis Weber. All rights reserved.
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.
This newsletter is no longer being published.
I do not sell, rent, or give my mailing list to anyone.