Newsletter

Issue 30, 21 January 2000

ISSN 1442-8652

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

In this issue...

Techniques for reviewing and editing online help
Conference announcement: AODC 2000
Book reviews: Writing for the web, Web style guide, and Poor Richard's e-mail publishing
Typographic spaces - TrueType font now available
Editorial ethical dilemmas
Comment on Newton's Telecomm Dictionary
Comment on sex and gender
Master Converter program for units of measurement
Contributors wanted
Advertisement: Electronic editing book
Advertising policy
Subscription information

---

Techniques for reviewing and editing online help

I haven't found any easy way to mark up a help file while editing it, to show what I've changed (similar to Word's "Track Changes"). Looking through archives from the WINHLP-L and TECHWR-L lists, I've identified the following possible techniques for editing online help in WinHelp format. Some of these can also be used with HTML-based help and other forms.

Your suggestions on other methods or improvements in these methods (such as tools to use) are welcome.

1. Editors and reviewers receive printed copies of the help (produced in various ways, including output as a manual with popups as footnotes, available in ForeHelp [and other HATs?]) and write their comments on the pages. Compiled help may or may not be distributed with the printed copies. This appears to be the most common method.
    
2. Editors and reviewers use compiled help, print topics they want to comment on, and write on the paper.
    
3. Editors and reviewers use compiled help and make comments using annotations, which are stored in a .ANN file, usually in the same place as the help file. There is no easy way to print out this file because it's not stored in a text format. After creating the annotations, you should be able to include the .ann file when you return the help file to the writer.
    
4. Editors and reviewers use compiled help and type their comments into a separate file or e-mail message.
    
5. The help is distributed as Word or RTF files; editors and reviewers edit or insert comments into the file. Again, compiled help may or may not be distributed with the editable files.
    
6. Help RTF files are saved as PDF; editors and reviewers attach annotations to the PDF files (requires Acrobat, not just Reader). A variation: reviewers print the PDF files and write on the paper.

To ensure reviewers see all topics in compiled help, have them turn "Help Author" (a menu option in the Help Compiler Workshop) on and then they can go through every topic. They will see topic ID information in the title bar of the help as they navigate around.

Various methods of keeping (or viewing) popup topics in context were mentioned.

Obviously, each of these methods has advantages and disadvantages, some of which depend on the willingness of the writers, editors and reviewers to use a particular method; some of which are more related to available technology; and some of which depend on the stage of development of the help system and/or the software it documents.

Back to top

---

Conference announcement: AODC 2000

The 3nd Annual Australasian Online Documentation Conference will be held at the Brisbane Sheraton in Australia from 12th to 14th April, 2000.

The Conference features speakers from the US and UK, as well as local experts, and is a must for people involved in creating online procedures, manuals, intranet content, or help systems. Cost is $995.

Call Penny Bradley at HyperWrite on +61-(0)3-9853-3666, e-mail pbradley@hyperwrite.com.au, or register through http://conference.hyperwrite.com.au.

Back to top

---

Book reviews: Writing for the web, Web style guide, and Poor Richard's e-mail publishing

I've reviewed three books which you might find interesting and useful:

Writing for the Web, by Crawford Kilian, Self-Counsel Press, 1999, paperback, ISBN 1551802074
http://www.jeanweber.com/books/kilian.htm

Web Style Guide: Basic Design Principles for Creating Web Sites, by Patrick J. Lynch and Sarah Horton, Yale University Press, 1999, ISBN 0300076754
http://www.jeanweber.com/books/webstyle.htm

Poor Richard's E-mail Publishing, by Chris Pirillo, Top Floor Publishing, 1999, ISBN 0966103254
http://www.jeanweber.com/books/emailpub.htm

Back to top

---

Typographic spaces - TrueType font now available

Lindsay Rollo lrollo@paradise.net.nz writes,

"Version 4 (January 2000) of spaces.ttf is available from:
http://ourworld.compuserve.com/homepages/macdonnell/OtherAuthors.html#lindsayrollo/SPACES.EXE

"WPWIN does not provide for typographic spaces - that is fixed spaces of various widths that are proportional of the base font size. At least three typographic spaces are usually available in dedicated DTP programs. This self-extracting file [191 kB] includes a TrueType font for creating typographic spaces [licensed for personal use], and explanatory notes and examples about the uses for typographic spaces in general documents of all types and particularly for compliance with ISO standards and academic publishing standards in scientific, technical and professional journals, reports and publications. The notes are in PDF format, and include a macro example for WordPerfect 8.

"Also included are six enhanced macros created by Barry MacDonnell.

As I say in the explanatory notes, Spaces.ttf can be used equally well with other word processors supporting TrueType fonts, but I am not competent to write the appropriate macros. I'm perfectly happy to supply ASCII text of their structure to help other create their own macros in the code of the word processor of choice."

Back to top

---

Editorial ethical dilemmas

A reader, who prefers to remain anonymous, wrote:

"I am at present doing a paid test editorial/fact-checking job. I can not go into details ... but while researching everything, I have the distinct impression that the author is repeatedly purposefully stretching facts. It gives one a queasy feeling. I mention it to you, because in such situations one can imagine losing a job because one did it too well. It's a bit too early to tell in my case, but it seems to me this must be a very real risk sometimes.

"... with the Internet, web search engines and searchable web sites (e.g. libraries, newspapers, etc.) the capacity for private individuals, even in the outback, to check things should give truth stretchers second thoughts about their activities..."

The same reader asked:

"What would you think of some who says "The Podunk Times says bla blah blahh blahhh blahhhh" and the original text in the Podunk Times was "blaa blah blahh blahhh blahhhh". That is, my writer has lifted a very high proportion of the original text, changed it ever so slightly, points out where it comes from but doesn't quote it?"

Anyone like to comment?

Back to top

---

Comment on Newton's Telecomm Dictionary

Elizabeth R. Stone estone@mc.com wrote,

"[Re} Newton's Telecomm Dictionary. I used to edit for a telecomm hardware/software company, and I discovered that although Newton's is a valuable resource, it's quite quirky. For example, he includes entries for the planet Betazed (Star Trek: The Next Generation), his daughter, and his wife. He also spells T1 and E1 improperly -- he hyphenates them (T-1, E-1). I checked the BellCore specification which defined these protocols, and confirmed my findings with the ACM and the IEEE. The correct styling/spelling does not have hyphens.

It seems like a very petty point, but (as you probably know) editors *love* these things. I'd certainly continue using Newton's, but I would not consider it to be the Absolute Last Word and Determining Authority for all telecomm terminology. Also, it is revised approximately twice a year, and it may be worth keeping up with the most recent version, depending on one's company's place in the telecomm industry.

Back to top

---

Comment on sex and gender

Martin H. Heisrath Heisratm@issc.belvoir.army.mil wrote,

"I recently read your article dealing with the difficulties in handling the issue of masculine and feminine pronouns. Thanks for putting it together, it will come in handy in showing my folks here what I mean.

The only addition I would suggest (although it may be off-topic) is the typically improper use of the word gender. Gender is properly used only for addressing concerns of grammer. Sex applies to everything else. I know that using the word gender improperly is the more widespread approach, but it is still wrong. As word people, we all have a list of peeves that make us cringe, this is one of mine.

"My sex is male.
The gender of the noun male is masculine. "

Back to top

---

Master Converter program for units of measurement

In response to my notes last issue, Joyce Huddleston joyce@huddleston.co.uk wrote,

"A favourite program for converting units of measurement to add to your tools page.

"The progam I have used happily for several years is Master Converter. This is a shareware conversion program supplied by Savard Software. Contact details are e-mail: feedback@savardsoftware.com and URL: http://www.savardsoftware.com. Once you have registered and paid your [US$15] fee (credit cards accepted), you receive regular updates.

Back to top

---

Contributors wanted

I'm looking for people to contribute some articles, or tips, or short notes about almost anything related to editing, to this newsletter. If you have something relevant to share, please send it to me! I'm sure the readers would appreciate some contributions about different working styles, materials and clients.

Back to top

---

Advertisement: Electronic editing book

Electronic editing: Editing in the computer age
by Jean Hollis Weber
Published by WeberWoman's Wrevenge
248 pages
ISBN 0646380370

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
http://www.jeanweber.com/books/e-edit.htm#order

or send e-mail to jean@jeanweber.com

Back to top

---

Advertising policy

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.

Subscription information

This newsletter is no longer being published.

Privacy statement

I do not sell, rent, or give my mailing list to anyone.

---