Newsletter
Issue 57, 7 March 2002
ISSN 1442-8652
Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com
In this issue...
More on wording of instructions for using software
New book - Taming Microsoft Word 2000 now available!
More on editorial overviews and developmental editing
My style guide article is on the Techwhirl site
Australian Online Documentation Conference
Book review: Technical Communication: Strategies for College
and the Workplace
Tracking advertising results: Adminder
Advertisements
Newsletter server: AWeber
Diversify your business and your
income
I host this website on Server101
Subscription information
More on wording of instructions for using software
Many thanks to Geoff Hart ghart@videotron.ca, who wrote (in response to my Feb. 12 newsletter) to point out a major flaw in my suggestion in Tip 2. I had said,
<<Tip 2: Wording of instructions for using software
... 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?
... 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.>>
Geoff says: A modified version of one of your examples shows how this works:
23. To use your Internet-enabled microwave oven, open Internet Explorer's
"Cooking Equipment" menu and select "Nuke it, baby!"
Why do it this way? The reader immediately sees whether the command applies
to them, and where they are in the current task. (If the step is not relevant
or is optional, they can stop reading and skip to the next step.) ("Yup, I
want to microwave something.") Once they've decided to read further, they
immediately see where to go. ("There's that darned Equipment menu!"). Last
but not least, they read what to do ("There's the Nuke command!")--and that
answers the question that began this whole procedure in the first place: "how
do I microwave something over the Internet?"
I've finally revised and updated my book "Taming Microsoft Word" with additions
and changes specific to Word 2000. At the moment it's only available in downloadable
PDF form; I should have printed copies available by the end of April. You
can read the table of contents here:
http://www.jeanweber.com/books/tamewd2k.htm
That page also gives information on pricing and how to order. If you bought
"Taming Microsoft Word" after January 1, 2002, you can upgrade to a PDF of
the new edition at a reduced price.
(Yes, I know Word XP is out, but I'm always a release behind, and many of
the people I work for are not planning to upgrade until or unless they have
to.)
In issue 52, 20 October 2001, I gave an example of what I called an editorial
overview of a manuscript that had been submitted to an Australian publisher.
Recently, someone asked on the technical writers' list about reviewing a book
manuscript: "I am quite used to reviewing style, grammar, consistency, etc.,
but I am asking for your help in determining what else I should consider."
Geoff Hart beat me to the answer by saying, "I assume you mean that this
is a pre-editing or developmental editing review? If that's the case, then
you need to review the book for completeness (covers all the required topics?),
appropriateness for the intended audience (e.g., language, level of detail),
and consistency with the larger body of knowledge (i.e., did the author do
their homework).
"You'll probably also want to examine some substantive editorial issues
such as whether the sequence is logical, whether there's appropriate use of
graphics, whether the book makes for an easy read, and so on. You might even
want to consider whether someone else has already published an identical book,
and if so, how it compares to the present book. In short: Would you buy this
book? If not, why, and how could that be fixed?"
Recently I revised my article on style guides and added an example, as requested
by many people. The result has been published on the Techwhirl website for
technical communicators:
http://www.raycomm.com/techwhirl/magazine/writing/styleguide.html
The article on my website is now of historical interest only, and I may
replace it with a copy of the new article.
As always, I recommend the Techwhirl site as a great resource for technical
writers and editors.
AODC 2002, the Fifth Annual Australian Online Documentation Conference,
will be held 17-19 April at the Sheraton Towers Southgate Hotel in Melbourne.
The Conference will feature a collection of expert speakers from around
the world, including authors of a number of important technical writing, help
and content authoring books. New products will be launched, including Quadralay
WebWorks Publisher for Microsoft Word, and Virtual Media RePublico. You can
also see the latest offerings from AuthorIT, Adobe, eHelp and ComponentOne.
The conference is aimed at writers: people developing online content, writing
manuals, procedures, help, quality management systems, Intranet content, or
public Web documents.
Full details, including registration information, can be found at http://www.aodc.com.au/.
For a colour brochure, please send your mailing details to Penny Bradley at
pbradley@aodc.com.au.
By Dan Jones and Karen Lane, (Pearson Education), Longman, 2002, ISBN 0205325211
This textbook would also make a good self-study book for someone considering
a career change into technical communication. It covers audience, planning,
collaboration, gathering information, and organizing and managing information;
writing, designing, illustrating, and editing; job search and professional
development, including interviewing and presentation skills; common documents
such as procedures, processes, specifications, proposals, reports, and instructions;
and an overview of grammar issues, documentation styles, and other mechanics
of good prose.
Obviously any book with such a wide scope can only give the reader an introduction
to the topics, but this book does a very good job of that introduction, combining
academic theory with solid, practical information from practitioners. The
text is supplemented by marginal quotes from working technical communicators
and a series of profiles of successful professionals. I'm delighted to note
that I am one of the people quoted and profiled, but I'd recommend this book
even if I weren't in it.
Associated materials include an instructor's manual, companion website,
and other resources for instructors and students.
I've recently started using Adminder, an ad-tracking service, to keep track
of things like how many people:
I'm sure I'll think of lots more uses as I go along. I've already concluded
that I've been wasting a lot of time by not knowing where traffic is coming
from. I can guess -- sometimes with a fair degree of accuracy -- but having
statistics sure makes a difference. I've known this for years, but until the
past two years I've not been in a situation where I needed to put it into
practice.
If you do any kind of marketing on the Web, you need an ad tracking system.
Adminder is one of several good ones that are available. For more information,
visit
this site.
(Advertisement) AWeber is a paid service that provides follow-up autoresponders and other
functions in addition to acting as a mailing list server. I use 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. Learn more about them
here.
(Advertisement) While you've been reading the above, thousands of people all over the world
have been working to put money in my pocket. By this time next week, YOU could
be making extra money too.
Get full no-obligation information here.
(Advertisement) 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.
© 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. This newsletter is no longer being published. I do not sell, rent, or give my mailing list to anyone. Home | About
| Books | How
to | Links | Newsletter
| Business | Site index
| Search Articles © Copyright by their authors. Last updated 7 March 2002
This suggestion conflates two issues: navigation, and context. The problem
with the "consensus" is that it addresses only the former, not the latter,
and thereby focuses on the procedure rather than the task the user is performing.
That's ironic considering that your tip 1 recommended remembering to tell
readers why they're doing something.
New book - Taming Microsoft Word 2000 now available!
More on editorial overviews and developmental editing
My style guide article is on the Techwhirl site
Australian Online Documentation Conference
Book review: Technical Communication: Strategies for
College and the Workplace
Tracking advertising results: Adminder
Newsletter server: AWeber
Diversify your business and your income
I host this website on Server101
Subscription information
Privacy statement
© Copyright Jean Hollis Weber, Technical
Editing Consultant
WeberWoman's Wrevenge, Airlie Beach, Qld., Australia, jean@jeanweber.com
ABN 18 005 740 467 
http://www.jeanweber.com/news/tenews57.htm