Technical Editors' Eyrie Photo of Osprey
Resources for technical editors Home page About technical editing Books Tips, techniques and checklists Links to other resources Newsletter archives Site index Search this site Business basics: marketing, website development, and more

 

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:
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. A more complete response would be as follows:

  1. Establish the context. (Why am I doing this?)
  2. Tell them where to go. (Which menu should I open?)
  3. Tell them what to do when they get there. (Which command should I select?)

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?"

Back to top


New book - Taming Microsoft Word 2000 now available!

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.)

Back to top


More on editorial overviews and developmental editing

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?"

Back to top


My style guide article is on the Techwhirl site

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.

Back to top


Australian Online Documentation Conference

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.

Back to top


Book review: Technical Communication: Strategies for College and the Workplace

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.

Back to top


Tracking advertising results: Adminder

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.

Back to top


(Advertisement)

Newsletter server: AWeber

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.

Back to top


(Advertisement)

Diversify your business and your income

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.

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.


© 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.