The Technical Editors' Eyrie Newsletter

Issue 41, 18 October 2000

ISSN 1442-8652

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

In this issue...

Feature Article: Writing one book for more than one audience
Now available - Editing Online Help
Production editing online help (extract from Editing Online Help)
Deciding where to put commas
Question time: Capitalization
Where has the WINHLP-L list gone?
Tools: An enthusiastic plug for FAR
ForeHelp discussion list
Dreamweaver discussion lists
Pre-order Frame 6 Revision to Mastering FrameMaker 5
Subscription information

Feature Article: Writing one book for more than one audience

A common problem for writers and editors is the book that must be used by more than one audience. Here's what I did on a manual for a software project a few years ago.

The client wanted one manual for marketing, database administrators, and data entry people. Although the last two groups were both users of the software (at quite different levels), the information needed by each of the three groups had very little overlap.

The client would not consider a series of books, each aimed at a different audience, so I produced a book that had three clearly defined parts, stated which part was for whom, and divided the information to minimize overlap. The manager was happy with that solution, and (because the whole thing was only around 100 pages) I agreed that it was a useful document.

The programmer, however, was unhappy with not having all sorts of explanations and digressions in the data entry section. He argued that the data entry people "needed to know" that information. I argued that I had spoken to some of those people (who were almost exclusively temporary typists brought in for a few days each month to do the data entry) and they found the explanations confusing and in the way -- so they had given up on using the old manual. (Does this story sound familiar?)

I made their section of the book into a very straightforward step-by-step set of procedures, with diagrams showing where they were in the cycle of end-of-month processes, and clear statements of what they needed before they started, what to do, and what should happen if they followed the procedure and the system worked correctly. I had short cross references to a Troubleshooting section if whatever they were doing didn't work as described. The Troubleshooting section contained most of the programmer's digressions.

Other explanations and digressions, along with a lot of other technical information which would only be needed (and probably only understood) by the data administrator, went into another part of the book.

Because everything was in one book, data entry people could, if they wished, read that information as well, but it didn't get in their way. And both data entry people and the database administrator could read the marketing section about features and benefits, and how this product fit in with other products the company was using.

So the manual contained all the details, but was divided by audience. The data entry people were delighted, and said so -- and questions to other staff dropped dramatically, which delighted the manager. The programmer remained irritated and unconvinced, but he left soon after anyway, having done his job. I never found out what the database administrator (who joined the company about the time I finished the book and left) thought of it.

One book in three parts would not have worked as well if the program had required 1,000 pages of technical information, but in those circumstances I think it would have been even more critical to extract the data entry procedures and put them in a separate chapter, section, or book of their own.

Now available - Editing Online Help

by Jean Hollis Weber

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.

In this book, you'll discover:

The principles of planning, writing, and editing online help
The ten most common complaints that users have with online help, the causes of the underlying problems, and ways to identify and cure those problems
The eleven steps in the ideal help development process, their benefits, and the problems that arise when a step is left out
What to include in the specifications, outline, and map for your help project
Techniques for editing, reviewing, and testing the help

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

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.

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

Production editing online help

(extract from Editing Online Help)

At the production editing stage, you're looking for display and linking problems that have slipped through the other stages of editing. Most such problems should have been detected and fixed earlier in the development process. For example, the help prototype stage should have included testing file conversions, graphic formats and other display issues and solutions to major problems should have been found at that time. Copyediting or other checking of earlier drafts of the help should have found most of the problems discussed in this section, but last-minute changes in one part of the help system sometimes have unexpected effects on other parts of the system.

If you've been doing most of your editing on paper up to this point, then production editing is vital. Most online display problems cannot be seen on a printout, and some things that look wrong on a printout actually display correctly on screen. Therefore you must view the help online, preferably on a monitor of the size and resolution that your users are likely to have. If some of your users have laptop computers, be sure to test the help on them too.

In addition to checking for display problems, check that:

The final build includes all topics that should be there, and no topics that should not be there, especially if the project has used conditional text or more than one source file.
All the errors found during copyediting have been corrected.
Any notes from one team member to another have been removed.

Deciding where to put commas

by Geoff Hart ghart@videotron.ca

[Written in response to a reference to Carolyn Rude's opinion "even though we have a tendency to want to insert commas where we pause or 'breathe' while reading a sentence, punctuation is logical--not biological!" in her book Technical Editing.]

My emphasis is not on where you pause to breathe, but rather on where you'd logically catch your "mental breath", which is a very different thing. Commas mark off the main clauses of a sentence because that's where readers pause to figure out what's just been said (e.g., to provide the context for the rest of the sentence), not because of the rules of grammar.

Commas serve as your clue that you've reached the end of a clause and can now pause to figure out what it means before proceeding with the rest of the sentence. (Just as periods indicate the end of a complete sentence.) Try deleting commas from sentences that contain a long introductory clause and you'll still be able to read the sentence, but if you pay attention to your thought process, you'll find yourself working harder to establish where the introductory clauses end.

Emphasizing the role of grammar in defining punctuation places the cart before the horse: grammar exists to describe why we write the way we do and teach new writers the patterns of writing that have been proven effective (or at least that we've all agreed to follow). It does not explain why we write the way we do, but rather describes it.

The practice of putting a comma where you pause to breathe comes from _creative_ writing, which in turn inherited the practice from oral storytelling. Many of the best writers write in such a manner that you can hear the words in the silence of your head just as if the author were reading the story aloud to you. (C.S. Lewis comes to mind, since I'm just reading Narnia to my kids.)

Obviously, if you're writing something that's intended to be read aloud, using commas to indicate "pause here to breathe" makes perfect sense. It also establishes a natural, familiar rhythm. In the context of technical writing, that kind of cue isn't necessary (nobody would read a software manual aloud to their children, other than in a desperate effort to put them to sleep), and I suspect that this is what Caroline Rude was trying to say in her statement.

Question time: Capitalization

A reader asked,

"I was always taught not to capitalize 'winter, spring, summer, or fall.' One of my co-workers did so and I changed it. She then told me that since we were in a university setting, it was proper to capitalize these words.

"Example: 'He has been a student since Fall of 1998.'

"I'm not sure of this one so need some advice. I might be able to understand if she had used it in this way - 'He started school in the Fall semester 1998.' (I'm still not sure of this one and would not use it this way.)"

I answered,

"I don't usually capitalize the seasons, either (I'm a big fan of minimalist capitalization), but I don't think it's incorrect to do so. I'd probably capitalize Fall in your example sentence, because I read it as shorthand for 'the Fall semester.'

You ought to ask some of these questions on the copyeditors' list; I'm sure you'd get rather more definitive answers from them than from me. I'm more into structural editing than the details of copyediting, and I've had too many years in Australia where many of the rules are different from American rules."

Where has the WINHLP-L list gone?

While I was overseas and not reading my lists, one of them (WINHLP-L) packed up and moved. I've corrected my resource pages, but thought I should mention it here, just in case you're wondering too.

HATT (Help Authoring Tools and Techniques) is now on yahoogroups. (WINHLP-L is being slowly shut down by Humber College, which has been hosting the list for many years.) The members discuss much more than WinHelp, so a change of name was appropriate. Lately there's been much discussion about tools for creating and managing HTML-based help. Dreamweaver is a popular choice.

To subscribe, send e-mail to HATT-subscribe@yahoogroups.com. You'll get a confirmation note after the list moderators approve your subscription (this is to keep out spammers).

To contact the list owner directly: HATT-owner@yahoogroups.com

Web address for this group: http://groups.yahoo.com/group/HATT

Note that off-topic posts on this list are frequent and not discouraged; the group has a long-standing culture that thrives on chatter. In this it's similar to Copyediting-L, but without the filtering mechanism before digests are sent out.

Tools: An enthusiastic plug for FAR

FAR is a shareware program from http://www.helpware.net/. It is a collection of utilities used in conjunction with the HTML Help Workshop for manipulating HTML files, including creating and editing HTML Help tables of contents; finding and replacing across multiple files; searching for all HTML, image, and media files and compressing them into a single HTML Help file; compiling HTML Help from the contents of a folder; and adding a table of contents and an index to a Web site.

Some of FAR's features (particularly find-and-replace) are very useful when dealing with any text files. I used it to clean up the HTML versions of my Editing Online Help book and to improve on the HTML Help version. It's well worth the (small) price. And it's Australian -- even better!

ForeHelp discussion list

Users of ForeHelp/ForeHTML (my preferred help authoring tool) have a tool-specific group on yahoogroups. The membership list is short, so the traffic isn't huge, and off-topic posts are discouraged.

To subscribe, send e-mail to forehelp-subscribe@yahoogroups.com

The Web address is http://groups.yahoo.com/group/forehelp

Dreamweaver discussion lists

Users of Dreamweaver (my preferred website development tool) have a choice of two tool-specific groups on yahoogroups. These lists have hundreds of members and traffic appears to be heavy, although off-topic posts are discouraged.

Dreamweaver Newbies

To subscribe, send e-mail to dreamweaver_newbies-subscribe@yahoogroups.com

The Web address is http://groups.yahoo.com/group/dreamweaver_newbies

Macromedia Dreamweaver (for beginners and experts)

To subscribe, send e-mail to Macromedia_Dreamwvr-subscribe@yahoogroups.com

The Web address is http://groups.yahoo.com/group/Macromedia_Dreamwvr

(Note the abbreviation of Dreamweaver in these addresses.)

Pre-order Frame 6 Revision to Mastering FrameMaker 5

Thomas Neuburger thomasn@twelfthnight.com wrote:

Here are the particulars:
Title: The Masters Series: FrameMaker 6
Price: US$36.00 before 11/15 -- US$45.00 thereafter
Publisher's imprint: Twelfth Night Books
ISBN: 1-930597-01-0

We expect to have bound books in the next eight weeks. You can get a 20% discount on orders placed prior to November 15.

Web Ordering -- To order using a credit card, go to any of these locations:

TECHWR-L website http://www.raycomm.com/
FrameUser's website http://www.frameusers.com/
Twelfth Night Books http://www.twelfthnight.com/

All transactions are processed using a secure server hosted by Mindspring Enterprises.

Non-Web Ordering -- To order via snail mail, make out a check or money order to "Thomas Neuburger" and send it with your email address, phone number, and "ship to" location to:

Thomas Neuburger
8127 NW Hazeltine Street
Portland OR 97229
Ph: 503-297-1675

(Editor's note: Contact Thomas, not me, if you have any questions about his book.)

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 20 September 2001