Technical Editors' Eyrie Newsletter
Issue 68, 13 December 2002
ISSN 1442-8652
Editor: Jean Hollis Weber
jean@jeanweber.com
In this issue...
Style guides for training materials?
How to format a procedure with only one step?
Abbreviations for metric measurements
Editorial "reading ring" for online help?
Internationalisation of documentation
Cost-effective ways to run a quality publications department?
More about OpenOffice.org Writer
I'm on Amazon.com!
Subscription information
This issue contains a lot of correspondence. I'm glad that so many people write to me with suggestions or asking for advice. I do not publish correspondents' names or addresses without their permission, but please -- if you do write, and you don't want your letter published, even anonymously, then say so in the note.
Style guides for training materials?
A reader wrote,
"I have been doing technical writing and some editing for the last six years.
Normally, I write user manuals for mainframe and web-based systems and I have
lots of good information on layout, writing, etc. Lately, I have been asked
to produce workbooks for training procedures and train the trainer documentation
for classroom teaching.
"I was wondering if you could point me to some websites or suggest some resources.
"I have no style guide that seems to satisfy my users. I have tried to model my documentation after university textbooks and workbooks and other externally professionally produced textbooks but this design style has been met with limited enthusiasm.
"Also, my internal customers are crazy about adding graphics to the documents but I was taught that that lends an amateurish, if not cartoonish look to the documentation and I would like to point to a credible reference, if one exists, that this is not a standard practice in writing. Is there a standard for workbooks or training documentation or is creativity the name of the game?"
My response,
I'm sure there are conventions (possibly not standards) for workbooks or training
documentation, but I'm not familiar with what the conventions might be. On
the few occasions I've done some, I've used a template provided by the client.
I've also used some training docs that others have produced (when taking a
class). None of those used lots of gratuitous graphics, except for some icons
of the "tip" variety.
On the other hand, I'm thinking that the immensely popular 'Dummies' books use cartoons and other graphics, and those books certainly don't look amateurish. (I personally don't like their approach, but lots of people do.)
So... I think that whatever makes your clients happy is the way to go: if they like cartoons, give them cartoons. Training is often such a tedious chore for many people, so why not make it more enjoyable for them? So much of what we have to put up with at work is so boring and dull.
The correspondent then wrote,
"Thank you very much for your advice. I could live with the 'Dummies' concept
of a template if that was what I had to work with. I am trying to write for
an internal customer who is difficult to appease and I was hoping to show
her samples of what other large reputable companies do.
"I did find "train the trainer" documentation from the U.S. military on training soldiers to use guns but it is very stark. I had seen training manuals produced by different pharmaceutical companies but again they are very functional and lackluster. I will keep doing my research."
If any readers can assist this person, please write to me and I'll pass on your suggestions (and publish them in the next issue of this newsletter).
How to format a procedure with only one step?
Another person wrote,
"I have a point of style to resolve, and I can't find any reference material
to answer the question. Can you help?
"I work in a technical environment, and we write software documentation.
"How do you format a procedure that consists of one step? Is it appropriate to use a single bullet or numbered step? Here is an example:
Creating a New Outlook Appointment
- From the calendar interface, choose New Appointment. This opens the new appointment interface.
"My personal preference is to not use this format. Since it is not a list of two or more items, it seems awkward to format it as such. What do you think?"
My answer:
I agree that formatting a single step as either a bullet or a numbered step
is awkward. I have occasionally used a bullet, just to set the step off from
the surrounding text, but I don't consider that to be an ideal solution.
Whenever I can, I revise the material to have at least two steps, so I can use a numbered list. In your example, surely there is another step or two involved in actually creating the new appointment in the calendar. Perhaps there is something you can usefully say, other than simply "fill in the fields and click OK" (or whatever) as a second step?
Abbreviations for metric measurements
Last month on the STCTESIG list, someone asked,
"Is there a rule for converting from American units to what the rest of the
world uses (i.e., metric)? We had a mandate from above to always use mm in
our product specs. However, we disagree. We want to use mm when it is less
than a cm, cm when it is less than a m, etc. What do you do?"
Someone else suggested,
"I have not heard any mandates to only use mm. But if you are required to
use only mm, then I suggest you use it only up to 10 mm and then use 10 to
an exponent (either negative or positive) for those larger or smaller units."
My response to both these notes:
Strictly speaking, "centi" is not an SI (International System of Units --
popularly called "metric") unit, so in Australia and probably other countries
using the SI system, measurements less than a metre are given in millimetres
(mm), not in centimetres (cm); in fact, in Australia most measurements up
to several metres are given as mm. Popular usage may include cm, but strict
scientific and technological usage doesn't. That's probably why you have received
the mandate you mention. Depending on the product you are writing/editing
about, using exponents might or might not be appropriate for the audience.
Editorial "reading ring" for online help?
Robert E. Porter rep@itrezzo.net wrote
to suggest,
"A proof-reading ring... an understandability check by occupational peers.
Maybe a bulletin board type thing that would allow people to request & receive
readings and comments/ suggestions from others in the same business. Most
users (if they read the help at all) read the help before they ever get to
see the application, so that the application is unavailable for one reason
or another. The help, then, must make an unseen/ unknown thing clear. A "reading
ring" might be of value in this respect. It really takes a special person
to read and comment on help/documentation who isn't already almost intimately
familiar with the product, which is exactly the user's predicament. If I had
a peer to look over my shoulder at my current help/ documentation task and
offer comments, I'd feel much better."
My response:
I like that idea, but I don't think it would work for most people because
of the confidentiality problem. Several times I've offered to do something
to act as a reader for someone, but the person couldn't get permission for
me to do so.
As an afterthought, I would add:
In situations where a product has been released and is available for purchase
and use by the general public, the help has been "published," so people could
provide this feedback to the author for consideration in the next revision.
Not an ideal solution, but possibly quite a lot better than nothing. I started
thinking about that because of my recent involvement with the OpenOffice.
org documentation group. The existing help file needs a LOT of work in many
areas. Because of the "open" nature of the product, there is a mechanism for
anyone to point out problems and offer suggestions. I'm sure that some aspects
of this approach could be adapted to another environment.
Internationalisation of documentation
Another question/suggestion from Bob Porter:
"You've addressed "gender-neutral" documents, but I've never seen anything
on toning-down English for international audiences. Microsoft employs writers
for the purpose, but what does the independent software author/help writer
do?"
My response, aside from "hire a freelance editor," is:
I've written a few things, which are no doubt hiding somewhere on my website,
but gathering them together and expanding a bit sounds like a great idea.
Actually I'm fairly sure there are whole websites devoted to that topic.
What do you mean by "toning-down English"? I can think of lots of possibilities, many involving avoiding cultural stuff like analogies involving sports, national holidays, seasons, and so on; but I wonder what you had in mind.
Bob Porter replied,
"I had in mind simplifying English that tends toward a technical vernacular.
"I'm currently struggling to document a JavaScript I've written to expedite part of the HTML Help writing process. I've realized that much of my audience will not understand such phrases as: "as read" or "when undertaking blah, blah, blah, ... ". They simply don't make sense in other languages. especially after translation.
"Given that Pacific Rim countries constitute a major portion of the world market, and that Australia is uniquely positioned as both an English-speaking country and a Pacific Rim country with cultural and economic ties to both, I thought you'd be in a prime position to offer guidance on authoring help/documentation for both communities.
"You mentioned that several related sites must surely exist already. Do any of them invite the input of Chinese, Japanese, Korean, Vietnamese and other Eastern Pacific communities? Do any of them feature organized suggestions from the same communities? Everyone seems to be doing their level best with respect to translation, but the results, as I'm sure you've seen, are generally less than comprehensible, much less understandable."
Cost-effective ways to run a quality publications department?
Joe Greber jfgreber@yahoo.com wrote,
"Am I the LAST technical editor who believes that hardcopy editing, which
FORCES the author to make his/her OWN corrections ---thereby improving the
author's skills (rather than ENABLING the author to make the SAME mistakes
over and over again!!)and MINIMIZING editor-induced ERRORS----is the MOST
COST-EFFECTIVE way to run a QUALITY publications operation????????????????"
I responded,
No, you aren't the last technical editor who believes that. However, in my
experience "improving the author's skills" is in fact NOT always the most
cost-effective way to run a quality publications operation. And indeed I've
found that many authors do learn from working with softcopy markup; in fact,
I'd venture to suggest that those who will learn from good editing will do
so, regardless of the markup type; and those who aren't going to learn from
good editing won't do so, again regardless of the markup type.
However, much of the time the impetus for soft-copy editing is practical and not necessarily because of preference: the author and the editor are on different continents, and mailing or faxing stacks of paper is not practical.
Joe Greber added, in a later note,
"You may also add to my comment that, at least here in the States, the EDITOR
all-too-often "submits" the AFTER-EDIT "clean" version to the author for approval---again
to MINIMIZE the oh-so-busy-author's involvement in 'unnecessary details'."
My comment:
I can't decide whether the sentence above is a complaint or merely an observation.
The phrase "all-too-often" suggests to me that it's a complaint. I think that
can be quite an efficient way to deal with manual production, especially in
the circumstances described in your next sentence.
In the same note, Joe Greber said,
"Please remember I'm talking about technical manuals, which (here in the States,
at least)rarely have an 'author' per se, but rather the all-too-often disorganized
'input' from a bunch of very busy (and very rarely TRULY literate) engineers."
My response:
In Australia, the engineers also are frequently people who speak English as
a second (or third) language.
General comments:
Seems to me all these things that Joe Greber appears to be complaining about
are good reasons why having the editor clean up the document in the most efficient
manner may well be the best way to run a publications department.
Note: I did have permission to reproduce this correspondence. I did not receive a reply to my response to the second note.
Comments from other readers are welcome.
More about OpenOffice.org Writer
I've added more information to my pages about OpenOffice.org Writer, starting at http://www.jeanweber.com/howto/openoffice.htm
I'm on Amazon.com!
Two of my books are now available as e-books through Amazon.com, but you'll need the (free) Acrobat E-Book Reader instead of ordinary Acrobat Reader in order to read or print the books.
Taming Microsoft Word 2002 http://www.amazon.com/exec/obidos/ASIN/B0000794Q9/ref=nosim/weberwomanswreve
Taming Microsoft Word 2000 http://www.amazon.com/exec/obidos/ASIN/B00007FEJB/ref=nosim/weberwomanswreve
Readers of this newsletter will probably prefer to buy the book through my own website and save US$2, as the e-book versions cost US$10 each instead of $8. http://www.jeanweber.com/books/tameword.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 available as emailed ASCII text.
To subscribe, use signup box on any page of this website.
To unsubscribe, see instructions at the end of each newsletter you receive.
Privacy statement
I do not sell, rent, or give my mailing list to anyone.