Issue 40, 22 September 2000
In this issue...
Editing Online Help -- new book coming in October 2000
Excerpt from Chapter 4 of Editing Online Help
An Internet discussion list about Help authoring
Who is a team player?
Feedback: A listserv/support group for editors?
Tools: Create PDF without Adobe Acrobat
I can now take payments through PayPal
How to donate money to this website
Advertisement: Electronic editing book
Many of you know that I've been writing a new book, titled Editing Online Help. It's due for release in October 2000. Some production details are still being worked out, but I intend to make copies available in four downloadable formats (PDF, WinHelp, HTML Help, and non-browser-specific HTML), CD-ROM (containing all four formats), and -- for those that insist -- hardcopy. Prices are also still to be determined.
If want to receive an announcement when this book is available, please contact me. firstname.lastname@example.org
A draft table of contents is here: http://www.jeanweber.com/books/olhbk.htm
Planners and writers should use this chapter and Chapters 5 through 9 to remind themselves of the types of problems often seen in help systems and how those problems can be minimized.
Many of the items described here are really in the realm of usability testing, but if that isn't done, it's up to the writer and editor to do their best to find and fix problems.
If you're editing a help project that has had time to do steps 1 through 6 (described in Chapter 1), you should not encounter many of the problems described in this chapter when you edit and test the help.
Unfortunately, too many projects don't go through all the steps, don't have enough time to do them thoroughly, or make many undocumented (usually last-minute) changes.
If you're editing a help system in one of those projects, you can expect to find problems and to have insufficient time to edit and test as thoroughly as you know is necessary. Even if you do have time for a thorough edit, the writers and programmers probably won't have time to fix all the problems.
If you find that no task and question lists are available, you should develop some of your own before attempting to edit help substantively. If you don't have time to do a thorough job, just identify the main categories of problems, give specific examples and suggestions for improvements, and leave the details until the next revision.
This chapter describes the ten most common complaints that users have with online help and the causes of the underlying problems, suggests ways to identify the problems, and refers to related chapters in this book for more details.
- I can't find what I'm looking for.
- I can't figure out what's going on.
- I can't figure out what will happen when I do something.
- There's too much detail.
- There's not enough detail.
- I can't get to the help when I want it.
- The program isn't working the way the help says it should.
- Help tells me what the system does, but not how to use it.
- I want a bigger picture of what this program can do.
- The help is inconsistent and badly written and formatted.
Chapters 5 through 9 give examples related to each problem and describe cures for the problems. Many of the diagnostics and cures are based on the task and question lists that should have been developed earlier in the help project.
The members of WINHLP-L have moved to a new list at yahoogroups, because WINHLP-L is slowly being shut down by its former host. The list is now called HATT (Help Authoring Tools and Techniques), to reflect the wide range of help systems now in use. It's rather PC-oriented, but questions on Mac and Unix help receive good answers as well.
Here's how to subscribe: HATTemail@example.com
or through this Web page: http://groups.yahoo.com/group/HATT
When I'm working with online help, I find this list quite valuable, although many of the discussions get a bit technical for me. Many members are very willing to help, and the collective knowledge of the group should be able to get you out of almost any help authoring problem.
This question generated quite a discussion on TECHWR-L earlier this year. If you're interested, search the TECHWR-L archives (at http://www.raycomm.com/techwhirl/) for posts starting 31 Jan 00 with subject lines including the words Team Player.
I was too busy at the time to contribute my comments, so I'll publish them here. Your responses are welcome.
- Focus on solutions to problems, not assigning blame
- Praise in public, criticize in private (to person involved, or to manager)
- Criticize behavior, not the person
- Do not gossip about other team members
- Do not frivolously interrupt the work of other team members
- Work toward a common team goal, rather than undermining efforts by actions
or inaction, or by pursuing a private agenda
- Contribute to group decision-making if given the opportunity
- Accept team or management decisions (unless illegal or unethical), rather
than constantly arguing and delaying productive work, especially when those
decisions are on matters that are mainly a matter of opinion
- Set goals, estimate time commitments as accurately as possible, and meet
deadlines, or warn manager as soon as a problem is identified
- Are careful not to hold up others' work unless delay is unavoidable
- Are tactful when reviewing or editing others' work
- Recognize the difference between rules and opinions or preferences
- Do not impose personal preferences on others when editing their work
- Are not offended if advice or suggestions are not followed
- Accept personal responsibility for their own work and acknowledge errors,
rather than looking for scapegoats
- Share, not hide, information
- Ensure that working copies of documents are available to other team members,
not password-protected or checked out for more than one day without uploading
- Are available for consultation, but set reasonable boundaries on interruptions
- If working remotely, keep other team members informed of where and when they are contactable
Last issue someone asked for suggestions on a listserv/support group for editors, that addresses the psychology of editing.
Several people wrote to suggest Copyediting-L, and one person recommended Edline, from the Electric Editors. Here's the contact information for both lists.
The members of the Copyeditors' List (also known as "CE-L") discuss a wide range of topics. Here's the Web page for the archives; it has a link to a page where you can join or leave CE-L or change your settings: http://listserv.indiana.edu/archives/copyediting-l.html
You can subscribe by sending a message "subscribe copyediting-l Your Name" to mailto:firstname.lastname@example.org
EDline deals with editorial matters, covering everything from spelling and hyphenation queries to business issues of relevance to freelances.
To subscribe you have several options. If you'd like to read EDline messages
as they are posted, either send a blank e-mail to email@example.com
or send a message to ElectricEds@bigfoot.com with "Subscribe EDline" as the subject line.
In Issue 35, I mentioned one resource for people who need to make PDFs only occasionally and who don't want to pay for a full copy of Adobe Acrobat. Here's another (free) resource: http://over.to/freepdf (October 2001: that address is no longer valid.)
Someone on a list said it's "Not half bad either, though I've found it a bit unstable with some colour graphics."
I haven't used it, so I can't comment, and I certainly am not making any recommendations.
(Revised 20 December 2003)
Last issue I mentioned that I was seeking small donations to help cover the out-of-pocket expenses of keeping this site on the Web.
One way you can contribute is through PayPal, which for some time has been available to residents of most countries (originally it was only available to US residents). http://www.paypal.com/
(Revised 18 November 2001)
You can now pay for my books through PayPal, which is available to residents of most countries.
I've updated the book-ordering page with the PayPal links. http://www.jeanweber.com/books/e-edit.htm
Electronic editing: Editing in the computer age
by Jean Hollis Weber
Published by WeberWoman's Wrevenge
A quick start guide for editing students, experienced editors making the switch from paper to online, and anyone who needs to write or edit electronically.
Available in both downloadable electronic (PDF) and printed forms. For details
on ordering a copy, see
or send e-mail to firstname.lastname@example.org
If you have a product or service of interest to editors, I'll be happy to consider including a short advertisement, for a modest fee. Contact me for details.
© 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.