The Technical Editors' Eyrie

Issue 51, 2 September 2001

ISSN 1442-8652

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

In this issue...

Creating and using an exclude dictionary
Book review: Poor Richard's Branding Yourself Online
Artificial tasks or real tasks?
Resource: Edit-Work.com
Use of colons to introduce a list
Australian chapter of the Society for Technical Communication Technical Publications Competition
More articles on the TECHWR-L site
A cure for accidentally removing items from Word's menus
Books available from Jean Hollis Weber
    Taming Microsoft Word
    Editing Online Help
    Electronic Editing
Subscription information

Creating and using an exclude dictionary

An exclude dictionary is a very handy tool for editors. You can use it to find correctly spelled words that are not the right ones for the situation or not your preferred spelling. For example:
    its - it's
    their - there - they're
    affect - effect
    gray - grey
    any words the writer habitually mistypes, such as "widow" for "window"

After you add words to the exclude dictionary, the spelling checker will question them the next time you check spelling. You can then decide whether the word is the correct one or change it if necessary.

Here's how to create an exclude dictionary in Microsoft Word:

Click New on the main Word toolbar to start a new, blank document.
Type the words that you want to put in the exclude dictionary. Press Enter after each word.
On the File menu, click Save As and navigate to the folder that contains the main dictionary. (You must save the exclude dictionary in the same folder that contains the main dictionary.) If you don't know where that is, search for files ending .lex, usually under Program Files or Windows, but it depends on your setup and which version of Word you are using.
In the Save as type box, click Text Only.
In the File name box, type a name for the exclude dictionary. This name must be the same name as the main language dictionary it's associated with, except for the file extension, which must be .exc. For example, the English dictionary in Word 97 is called Mssp2_en.lex, so you would name the associated exclude dictionary Mssp2_en.exc. This file covers both US and UK English.
Click Save and close the file.
You can edit this file any time you want, to add or delete words. If you want to disable it but keep it for future use, you can either rename it or move it to a different folder.

Book review: Poor Richard's Branding Yourself Online

by Bob Baker, Top Floor Publishing, 2001, ISBN 1930082142

This book is aimed at individuals such as writers, artists, musicians and other creative people. Thus it is quite relevant to any consultants, contractors, or freelances, all of whom need to market themselves and their services or products.

Topics covered include:

Understanding what branding is about and why you need to do it
Defining and developing your brand identity
Gathering your tools: hardware and software, domain name, website
Using e-mail effectively: signatures, autoresponders
Tips for using e-mail to convey brand identity
Your website: designing, hosting, search engines, tools
Publishing an e-mail newsletter
Making yourself known through others' e-zines and websites
Tips for writing attention-getting articles
Self-publishing and marketing e-books
Online networking: participating in lists, forums, newsgroups
Linking strategies
Offline strategies
Real-life success stories

Like most of the books in the Poor Richard's series, Branding Yourself Online brings together a lot of tips and techniques that I am already familiar with, but it also gave me several new ideas and a collection of Web addresses that I had not discovered on my own. Had I bought my copy of this book, it would have paid for itself immediately by pointing me to several new markets for my own e-books.

The author, Bob Baker, was for 10 years the managing editor of Spotlight, the US Midwest music magazine he founded in 1987. In 1995, he began publishing The Buzz Factor, a free e-mail newsletter and website that established his identity as a music-marketing resource for aspiring songwriters, musicians and bands. Bob has also established an e-zine and website called Quick Tips for Creative People and a companion website for this book, http://BrandingYourselfOnline.com/.

If you can't find this book at your local bookshop, you can buy it through Amazon.com or directly from the publisher, http://www.topfloor.com/pr/brand/

Artificial tasks or real tasks?

by Michael West Mike.West@oz.quest.com

[Editor's note: this article is slightly edited from a post on the TECHWR-L list, and is used with Mike West's permission. He took most of the examples from an excellent book, Developing Quality Technical Information: A Handbook for Writers and Editors, by Gretchen Hargis (Editor), Ann Hernandez, Polly Hughes and Jim Ramaker, Prentice Hall, 1997, ISBN 0137903200.]

I highly recommend this book, which was put together by a technical editing group at IBM's Santa Teresa laboratory. It is concise and yet full of practical examples.

Regarding "real" and "artificial" tasks, the book describes a real task as a task users want to perform, whether or not they are using your product to do it. Artificial tasks are tasks that are imposed by the product.

The book provides the following examples of real and artificial tasks.

Users want to edit a table, but the writer introduces this task as "using the table editor" instead of "editing a table".
Users want to count the records in a file, but the writer introduces the task as "using the CNTREC utility" instead of "Counting records with the CNTREC utility."

"Users want," Hargis writes, "information about how to perform real tasks, not a list of the buttons and controls in the product."

I can provide another example from an editing project in front of me today: a help topic labeled "Using <product name> startup parameters". I want this changed to "Changing <product name> start-up behavior" or something similar. "Using parameters" is an artificial task. Who "uses" parameters? (Actually, it's the software that "uses parameters," isn't it?)

This has relevance to headings and index entries as well. A user scanning the table of contents or index is much more likely to make sense out of "Counting records" than "using the CNTREC utility" - except, of course, in the case of experienced users looking for context-specific information because they already know something about the utility (and those readers will recognize either heading).

Hargis also cautions against misleading users by using pseudo-task headings. Pseudo-task headings start with vague verbs, such as "understanding" and "learning" and sometimes (as above) "using."

Here's a test. Next time you see a topic with a name like "Understanding the Interface," see whether it actually contains procedural steps for how to "understand," or whether it is just a description of the interface. If the latter, a more accurate heading is simply "The Interface."

Good headings produce a good table of contents, from which users can accurately predict what they will find in each section, and which do not require any specialized knowledge of the product to recognize.

(Jean's comment: When a style manual requires every heading at a certain level to start with the same part of speech, and when writers and editors are required to follow the rules, you often get stuck with headings like "Understanding the interface" because it's more important to get the rest of the content right than to obsess over a heading. In most cases, however, you should be able to work out the real tasks involved. Note that all of the above assumes a task-oriented document such as as a Users' Guide, not a legitimately function-oriented document like some reference manuals.)

Resource: Edit-Work.com

If you edit web pages, you have find EditWork.com a useful resource. It had several no-nonsense pages including:

Web editing and proofing
http://www.edit-work.com/webstyleguide/copyedit.html

Create editorial procedures for a web site
http://www.edit-work.com/howto/howtoprocedure.html

Use of colons to introduce a list

Helen Kastner hkastner@cisco.com wrote in regard to my item "Stressing what is important in a Sentence" in issue 50.

"I was very startled by this example in the section.

No: There are a number of reasons for this decision: (followed by several bullet points)
Yes: The reasons for this decision are:

All my style guides--including the Chicago Manual of Style, the New York Public Library Writer's Guide to Style and Usage, and Words into Type--state that a colon should not separate a verb or preposition from the respective object.

I'd be interested in your thoughts on this example."

My response:
"If the list is run-on, the colon is incorrect and should not be there. If the list is vertical (such as a bullet list), then the colon is quite common, at least in computer-related documents. It's certainly the IBM, Microsoft, and Sun style, which doesn't necessarily mean it's "correct" English, or even American. The "no-colon" style is also correct, especially in material other than computer-related documents."

Australian chapter of the Society for Technical Communication Technical Publications Competition

Call for Competition Entries

Have you or your company produced technical communication products that you would like to enter into competition for awards? Would you like your work to be recognized professionally by your peers? This call for entries is an invitation to participate in the Technical Publications Competition for the Society for Technical Communication (STC).

Call for Judges

Are you an experienced technical communicator? Do you have an interest in contributing to the development of technical communications? Do you want to build on your professional qualifications? If you answered "Yes" to any of these questions, you may be eligible to participate as a 2001 Society of Technical Communications (STC) Australia judge for the upcoming Technical Publications Competition.

For more information on entering or judging, please contact Ann Backhaus, Competitions Manager, abackhaus_35@hotmail.com

A cure for accidentally removing items from Word's menus

In issue 49 I mentioned how to use Word's "Work" menu for instant access to files you use frequently. In issue 50 I told how to remove files from the Work menu.

Now I have to warn you that the removal technique can be dangerous if you accidentally remove something from another menu. Thanks to the 1999 archives of the Copyediting-L list, here is how to get your menu options back without going through the whole customisation routine for menus.

Dan A. Wilson at The Editor's DeskTop editor@editorsdesktop.com says, "To reset any menu list to its default, simply right-click the menu bar and choose Customize, then left-click any Menu bar caption that has a damaged menu list. Now right-click that item, which now has a black box around it, and click the Reset button. The menu list will be restored, and items you inadvertently deleted from the list with the eraser tool will return."

Books available from Jean Hollis Weber

Taming Microsoft Word

116 pages
ISBN 0 9578419 2 2
Published February 2001

A quick reference for writers, editors, and others who need to use some of Word's more advanced features. This book is an expanded and updated version of Chapters 3 and 4 in my first book, Electronic Editing. Taming Microsoft Word is quick to read, yet packed with essential information.

A full contents list and information on downloading the PDF file and paying for it are available here: http://www.jeanweber.com/books/tameword.htm

Editing Online Help

155 pages
ISBN 0 9578419 0 6
Published October 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.

More information here: http://www.jeanweber.com/books/olhbk.htm

Electronic Editing

248 pages
ISBN 0 646 38037 0
Published October 1999

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

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

Newsletter

Issue 51, 2 September 2001

Privacy statement