Issue 51, 2 September 2001
In this issue...
Creating and using an exclude dictionary
Book review: Poor Richard's Branding Yourself Online
Artificial tasks or real tasks?
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
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.
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/
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.)
If you edit web pages, you have find EditWork.com a useful resource. It had several no-nonsense pages including:
Web editing and proofing
Create editorial procedures for a web site
"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."
"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."
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, email@example.com
In issue 49, I mentioned Geoff Hart's "User's Advocate" column on the TECHWR-L site, http://www.raycomm.com/techwhirl/usersadvocate.html and specifically his article "Sometimes Playing Dumb Makes Things Work Better". His other articles include:
- Designing for the other half
- Nobody reads manuals, do they?
- Sometimes you really can be too helpful
- The domino effect: Unforeseen consequences
- The needs of the many
- Examining and applying what we learned from Y2K
- Garbage in; garbage out: Using affordances
- Validity checks
- Devil's advocate
Another useful column for editors is Doug Isenberg's "Ask the Lawyer", http://www.raycomm.com/techwhirl/magazine/writing/legalhomepage.html. Topics include:
- Placing copyright notices in documentation
- Using parts of another company's documentation to supplement your company's documentation
- Understanding business communication copyright laws
- Using client logos
- Updating copyright notices
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 firstname.lastname@example.org 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."
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
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
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
© Copyright 2001, 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.