Newsletter 43, 19 December 2000, Technical Editors' Eyrie

Issue 43, 19 December 2000

ISSN 1442-8652

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

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
Subscription information

An index for the Eyrie, and other additions and changes

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.

Making Web pages viewable (and usable) in any browser

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.

Editing alternative text for images on Web sites

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

A good book on Web site usability

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

Copyediting online help (extract from Editing Online Help)

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.

Revision marking for HTML

David Knopf ( mailto:david@knopf.com ) 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:george@ghayhoe.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."

Australasian Online Documentation Conference 2001

The fourth annual Australasian Online Documentation Conference is scheduled for March 28-30 in Canberra. Conference details are available on the HyperWrite web site:

http://www.hyperwrite.com.au/conference/

Tools for counting words in HTML and PDF files

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.

WebBudget, http://www.webbudget.com/index.htm

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.

Another listserv/support group for editors

Margaret Cooter ( mailto:mcooter@bmj.com ) 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."

http://www.sfep.org.uk/

I couldn't find any reference to a list on SFEP's Web site, but perhaps it's in the "Members Only" section.

Book search site: AddALL

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.

http://www.addall.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 26 June 2003
http://www.jeanweber.com/news/tenews43.htm