Issue 43, 19 December 2000
In this issue...
An index for the Eyrie, and other additions and changes
Making Web pages viewable (and usable) in any browser
Editing alternative text for images on Web sites
A good book on Web site usability
Copyediting online help (extract from Editing Online Help)
Revision marking for HTML
Reprint of article on measuring the value added by professional technical communicators now on STC site
Australasian Online Documentation Conference 2001
Tools for counting words in HTML and PDF files
Another listserv/support group for editors
Book search site: AddALL
Now available: Editing Online Help by Jean Hollis Weber
I've finally added a "back-of-the-book" index to the Web site. It is far from complete, and I will be revising it frequently. You can reach it through the Index link on any of the main pages or newsletter pages, or go directly to this address: http://www.jeanweber.com/Indexer.htm
The index was compiled using HTML Indexer, a product which I recommend. You can get it from http://www.html-indexer.com/
I've also added a page of links to tools for developers of online help: http://www.jeanweber.com/links/tools_ol.htm. This list was correct in August 2000, but it is far from complete, and already several of the original links are no longer current. (I've noted them on the page.)
Lastly, I've been learning about cascading style sheets and slowly changing the pages to use CSS. In the process, I've discovered many problems in the layout of the older pages (produced when I was a novice with HTML). I'm trying to catch and correct all the layout glitches, so if you spot any that I've missed, please let me know the page and the problem.
I decided to change to CSS for several reasons. First, the use of CSS is recommended by the Web Accessibility Initiative as a means to providing browser-independent Web page presentation, where content and usability are more important than precise layout or "cool" design.
Sites intended mainly for entertainment can do what they like, but my interest is in information, business, and e-commerce, where I believe it's important not to exclude members of your potential audience by requiring them to use hardware or software that they may not have or wish to use. For businesses, excluding some of your audience is simply bad business (in my view), and for some groups, accessibility is a legal requirement, so you and I need to know how to achieve it.
One method is to provide more than one variation of each Web page, each optimized for a different audience; some sites have a "text only" page in addition to the graphics-intensive page. This can be a good solution from the users' point of view, but requires maintaining two sets of pages (or using some method to generate graphic or text pages from a central database). I think a better method, particularly for individuals or small organizations, is to design a page that "degrades gracefully" in browsers that don't support all the features you choose to include. Such a page may not look the same in all browsers, but it's functional in all of them.
The goal of the Any Browser Campaign ( http://www.anybrowser.org/campaign/ ) is to help people develop pages that can be used in any browser, including text-only browsers and those that read to the blind, yet still look good in modern browsers with the latest plug-ins enabled. Many people incorrectly assume that any-browser pages must be dull or look old-fashioned, but that is not true.
Unfortunately, the popular Web page authoring tools emphasize design over usability (and conversion tools are even worse, promising "pixel-perfect placement" on the page). Many designers either aren't aware of the usability issues, or consider those issues unimportant, or don't know how to use the tools to achieve an "any browser" result. (Designers who are aware of the issues and consider them important are often over-ruled by managers or clients.)
Check the Any Browser site for instructions, tips, and links to tools for designing, validating, and testing Web pages.
July 2002 note: See also this newsletter article for related information.
Among the many things that Web site editors should look at is the alternative text provided for images; that is, the contents of the ALT attribute. This text is important for several reasons, including assistance for those who use text- only browsers, turn off graphics to improve download time, or have their computer read aloud to them.
For some simple guidelines on using ALT texts in image (IMG) elements, see http://www.cs.tut.fi/~jkorpela/html/alt.html
Steve Krug, Don't make me think: a common sense approach to Web usability, New Riders Publishing, 2000, ISBN 0789723107. Order from Amazon.com
I was most impressed by this short book's clear statement of the issues and the examples the author presents of typical Web sites, inviting the reader to identify what's wrong with them and how to fix them, followed by one or several variations that he suggests.
This book would be a valuable addition to anyone's library, particularly if you need an authoritative source to back up your opinions on layout and navigation. It nicely complements other less visual books like Jakob Nielsen's Designing Web usability: the practice of simplicity, New Riders Publishing, 2000, ISBN 156205810X. Order from Amazon.com
Much copyediting can be done on paper, particularly in early stages of the project when you are looking at draft topics. However, some issues must be checked online. I discuss the online issues under production editing, but many people consider them to be part of the copyediting step. You might use two people to copyedit: one to check the text on paper and another to check for online display problems.
When copyediting online help (on paper or online), you should look for most of the same problems that you would check in printed documents; for example:
- Spelling and misused words
- Jargon, unfamiliar words, and inconsistent use of terms
- Grammar and punctuation
- Topic titles unclear, misleading, too long, or not in approved style
- Long, wordy sentences or paragraphs that should be turned into lists
- Misused or inconsistently used bulleted or numbered lists
- List items not in parallel style
- Inconsistent capitalization and punctuation
- Inconsistent use of bold, italics, color, or other highlighting
- Inconsistent style and presentation of procedures
- Long, complex, or branching procedures, or too many sub-procedures
- Steps out of order in procedures
- Link text unclear, misleading, too long, too short, or not in approved style
- Too many links, or links too close together
- Any other deviations from specifications
When copyediting online, add the problems listed in "Production editing online help" (see newsletter issue 41, http://www.jeanweber.com/news/tenews41.htm ). Here is some more information about finding and fixing display problems.
Online display problems usually come from three sources:
- File conversion to an online format from a word-processing or desktop publishing program
- The way text and graphics are displayed on screen (often a platform-specific problem)
- Poor choices by the designer or writer
Most problems can be fixed, but some must be avoided by finding another way to present the information.
Some common online display problems are in these areas:
- Graphics (blurry, wrong size, or unnecessary)
- Hotspots (links)
- Tables (display problems or wrong size)
- Bullets and numbered lists (display problems)
- Indentation (too much or inconsistent)
- Inconsistent help window sizes and placement
Chapter 9 of the book has more about each category.
David Knopf ( mailto:firstname.lastname@example.org ) made this suggestion on the HATT list, in response to a request for some way to do revision marking in HTML files, similar to Microsoft Word's revision marks:
"One possibility is to define two CSS classes ('deleted' and 'inserted') for example. You can apply these classes as you edit content and control their appearance through CSS. For example, the deleted class could be displayed as strikethrough text and the inserted class could be displayed as underlined text."
Reprint of article on measuring the value added by professional technical communicators now on STC site
George Hayhoe ( mailto:email@example.com ), editor of the STC's journal, Technical Communication, posted this notice to TECHWR-L:
"A special section of articles on Measuring the Value Added by Professional Technical Communicators, edited by Ginny Redish and Judy Ramey and originally published in the February 1995 issue of _Technical Communication_, is now available online at http://www.techcomm-online.org/shared/special_col.html
"This section of the Technical Communication Online site is accessible to all users without registration.
"Because the files used to produce this issue no longer exist, the articles are available as scanned PDFs only."
The fourth annual Australasian Online Documentation Conference is scheduled for March 28-30 in Canberra. Conference details are available on the HyperWrite web site:
Awhile ago the HATT (Help Authoring Tools and Techniques) list discussed tools for counting words in HTML files, particularly for translation. Some of the suggestions were:
TextCount for Windows, http://members.aol.com/textcount/
A word-counting program that works for Microsoft Word, WordPerfect, RTF, and HTML files, among others.
Counts the text in META tags, ALT tags, button tags, Java script content and other translatable text in a single Web page or over an entire site.
PDFCount For Acrobat, http://www.pdfcount.com/
A plug-in utility for Adobe Acrobat 3.01 and 4. Designed to quickly display PDF document statistics, including the number of characters, words, and pages and a document.
Trial versions of these tools are available, but I have not tried them.
Margaret Cooter ( mailto:firstname.lastname@example.org ) writes:
"Another listserv/support group for editors is through SFEP, the UK Society for Freelance Editors and Proofreaders... once you've joined SFEP, you can join the list."
I couldn't find any reference to a list on SFEP's Web site, but perhaps it's in the "Members Only" section.
AddALL is a book search and price comparison site that bundles several book search engines together and brings up the results quickly. I've found it very useful, particularly in tracking down titles that are in print but aren't in Amazon's catalog.
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.