Newsletter

Issue 56, 12 February 2002

ISSN 1442-8652

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

In this issue...

An author's view of electronic editing practices
Editing tips: Wording of procedures and instructions
    Tip 1: Watch for hidden assumptions
    Tip 2: Wording of instructions for using software
Correction to instructions for saving an exclude dictionary in Word 2000
My article on gender-neutral writing is on the Techwhirl site
Tools: Free ISBN barcode generator
Hardcopy or onscreen: Poll results so far
Feedback: Newsletter format - HTML or plain text?
New newsletter server: AWeber
Advertisements
    Copies of "Website Indexing" are available from me
    I host this website on Server101
    Books by Jean Hollis Weber
Subscription information

---

An author's view of electronic editing practices

Woody's Office for Mere Mortals #3.01 (subtitled "Editing in the real world") has some very interesting comments by Woody Leonhard about the way editors mark up his manuscripts electronically. Woody has published dozens of books (mainly about Microsoft Word), and all of the editing for many years has been done electronically. His experiences, and his opinions about those experiences, confirm some of my opinions about editing electronically. Some of his other comments gave me new food for thought.

Whether you agree or disagree with Woody's preferences, he is a good example of why you should discuss with writers what the best way to edit might be, instead of just imposing your methods on the writer. You can read the article, or other issues of Woody's various newsletters, at http://www.woodyswatch.com/wowmm/archives.asp

If you use Microsoft Office, and you don't already subscribe to one or more of Woody's newsletters, I strongly encourage you to do so. In addition to providing some good tips for using Office or Windows, the newsletters will keep you up-to- date on the latest patches and upgrades, including which ones to avoid because they cause more problems then they solve.

Back to top

---

Editing tips: Wording of procedures and instructions

Tip 1: Watch for hidden assumptions

One of my biggest complaints about a lot of instructions (both printed documentation and online help) is that they tell me *how* to do something but don't give me a clue *why* I might want to, or what it's for, or what the consequences might be if I make one choice or another. The assumption seems to be that the reader wants to do X but doesn't know how. I think that's often an incorrect assumption; sometimes it never occurs to me that X was a possibility -- I didn't know enough to even ask the question. And even if I did know I wanted to do X, I still might wonder what this piece of software was going to do after I made that choice.

I am reminded of this problem because the people who edit the books I write frequently point out to me that I am guilty of doing the same thing -- making an invalid assumption about what my audience knows. As soon as someone points this out, I realise they are correct and I add a few sentences to put the procedure into perspective.

In the past I've usually been the editor spotting the missing information; it's quite an eye-opener to be on the other side.

Back to top

Tip 2: Wording of instructions for using software

Procedures for using software often include instructions for filling in fields, selecting checkboxes, and clicking buttons in a dialog box. Writers often ask what's the best way to word those instructions.

Do you say, "Click x to do y" or "To do y, click x"?
Do you say, "Choose Save As from the File menu" or "From the File menu, choose Save As" or some other wording?
What is the best wording when you need to combine these ideas? For example, when readers can do several things on one dialog box, they may need to know the consequences of each choice, then how to implement their choice.

This topic was discussed recently on the help authors' list http://groups.yahoo.com/group/HATT. The consensus was to orient users first (tell them where to look), then tell them what to do. A variation was to tell them what the consequences are, then where to find the controls, then how (or what) to select.

Some examples of preferred usage follow. (The wording could be improved, and I'm sure you can find some better examples; the sequence is the relevant point here.)

"From the Cooking Equipment section of the Properties dialog box, select Use Microwave Oven."

"Choose the microwave oven: Properties > Cooking Equipment > Use Microwave Oven."

"1. Ensure that your food is not wrapped in foil (this will prevent the kitchen exploding). If your food is wrapped in foil, see the procedure for using a conventional oven, or remove the foil wrapping and place food in a microwave-safe container.
2. Choose the microwave oven: Properties > Cooking Equipment > Use Microwave Oven."

"1. Prevent your kitchen from exploding: ensure that your food is not wrapped in foil.
2. Choose the microwave oven: Properties > Cooking Equipment > Use Microwave Oven."

All of the above were preferred over the "action first" model (which was the model I was first taught when I started editing computer documentation years ago). In other words, the consensus was not to use:
"Select Use Microwave Oven from the Cooking Equipment section of the Properties dialog box."

Back to top

---

Correction to instructions for saving an exclude dictionary in Word 2000

In issue 53, I gave some instructions on where to store an exclude dictionary for Word 2000. Those instructions were a bit misleading, as I discovered when trying to do this myself.

In Word 97, the exclude dictionary must be stored in the same folder as the main dictionary, but in Word 2000, the exclude dictionary must go in the "proofing tools" folder, which may not be where the main dictionary is located.

In Windows 95, 98, or ME, store the exclude dictionary in C:\WINDOWS\Application Data\Microsoft\Proof

In Windows 95, 98, or ME *with profiles enabled*, or Windows NT 4.0, store it in C:\WINDOWS\Profiles\Username\Application Data\Microsoft\Proof

In Windows 2000, store it in C:\Documents and Settings\Username\Application Data\Microsoft\Proof

Other information given in that article is correct. For more on exclude dictionaries, see issues 51 and 53: http://www.jeanweber.com/news/tenews51.htm http://www.jeanweber.com/news/tenews53.htm

Back to top

---

My article on gender-neutral writing is on the Techwhirl site

Recently I combined and revised two of my articles on gender-neutral writing and submitted the result to the Techwhirl website for technical communicators: http://www.raycomm.com/techwhirl/magazine/writing/genderneutral.html

The two articles on my website are now of historical interest only, and I may replace them with a copy of the new article.

I recommend the Techwhirl site as a great, and growing, resource for technical writers and editors.

Back to top

---

Tools: Free ISBN barcode generator

I've been looking for an inexpensive ISBN barcode generator for several years. I finally found one -- and it's free from The College Park Press in Maryland.

You can either get a barcode generated from the website and e-mailed to you, or you can download the program, which is written in Python. I've tested the online version and the results look good. The generated barcodes are in EPS (Encapsulated PostScript). I wanted mine in WMF (Windows MetaFile) format, so I converted them using Paint Shop Pro 7. You could use many different graphics programs to do the conversion.

Here's the address: http://www.cgpp.com/bookland/isbn.html

Back to top

---

Hardcopy or onscreen: Poll results so far

Last issue I mentioned that I had set up another online poll, on the topic "Do you edit mainly onscreen or on paper?" Results as of 7 February were: 14 hard copy, 17 onscreen, 26 both.

I've now changed the poll so you can see the results online when you vote; sorry about not doing that sooner. If you haven't voted already, you can do so at http://www.jeanweber.com/news/index.htm

Back to top

---

Feedback: Newsletter format - HTML or plain text?

In response to my comments about possible newsletter formats, Roger L. Boyell boyell@ieee.org wrote, "Comparing your newsletter in plain text to the HTML version is like a candle compared to the sunlight. OK I'm exaggerating. But even with my slow modem the HMTL version loads swiftly... It's a pleasure to click on your links.

"I suggest that people who rejected the HTML version have been scared by Web designers who incorporate overcomplicated graphics, text-obscuring backgrounds, and endless redirections to ad servers before the intended page actually loads.

"Perhaps you should ask who among your readers is unable (rather than simply unwilling) to accept HTML-formatted newsletters."

Well, Roger, I am among those people who are able to accept HTML-formatted e-mail and newsletters, but don't want to. Even if nothing more complicated than a specified font and text size has been added, that still often makes it a hassle for me to read a message easily. However, I am working towards giving each of you an individual choice of which format you get. Stay tuned!

Back to top

---

New newsletter server: AWeber

This newsletter is the first one that I am distributing using my new mailing list service. AWeber is a paid service that provides follow-up autoresponders and other functions in addition to acting as a mailing list server.

I looked around for quite awhile before deciding to use AWeber. I didn't want to use one of the free services such as Yahoo! or Topica, mainly because I didn't want anyone else's ads tagged on the end of my newsletters. (Topica's paid service -- without ads -- was my second choice.) I chose AWeber for several reasons: the autoresponders, the price (which does not increase when the number of subscribers increases), the ability to send messages to a subset of the list, the ad tracking, and the reduced price for a second or subsequent list.

I am an affiliate of AWeber, so please use this link if you are interested in learning more about them. http://www.aweber.com/?48946

Back to top

---

(Advertisement)

Copies of "Website Indexing" are available from me

In issue 52 I mentioned a book titled Website Indexing by Glenda Browne and Jonathan Jermey, published in 2001 by a small press in Adelaide, South Australia. My review is here: http://www.jeanweber.com/books/webindex.htm

I now have some copies of this book for sale. Cheque/chck only. A$36.50 or US$20. Send to JH Weber, PO Box 640, Airlie Beach Qld 4802, Australia, AND e-mail me to say you've sent the check -- if I'm away from home, I may not get your check for weeks, but if I know you have sent it, I can mail the book to you.

Back to top

---

(Advertisement)

I host this website on Server101

My new web hosting company offers me more than twice the space for less than half the cost of my old hosting company. I've been very happy with the service, so I recommend it to you. I am an affiliate of Server101, so please use this link if you are interested in learning more about them. http://www.server101.com/?AID=5123

Back to top

---

(Advertisement)

Books by Jean Hollis Weber

Taming Microsoft Word

A quick reference for writers, editors, and others who need to use some of Word's more advanced features. More information here: http://www.jeanweber.com/books/tameword.htm

Editing Online Help

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. More information here: http://www.jeanweber.com/books/olhbk.htm

Electronic Editing

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. More information here: http://www.jeanweber.com/books/e-edit.htm

---

© Copyright 2002, 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.

---