Newsletter

Printer-friendly version

Issue 73, 21 June 2003

ISSN 1442-8652

Editor: Jean Hollis Weber
jean@jeanweber.com

In this issue...

Should technical editors be responsible for checking accuracy?
Paramedic method of editing
"Use cases" and "user scenarios" explained
Book: Promote Your Business, by Mary Morel
Book: Google Pocket Guide, by Tara Calishain and others
UCLA Extension online Technical Communication courses
For Australians: National Editors' Conference 17-20 July 2003
For Australians: Technical and Scientific Editing Workshop, 23 August 2003
My books: Taming Microsoft Word and others
Subscription information and privacy statement

---

Should technical editors be responsible for checking accuracy?

In May, the Techwr-l mailing list had a lively discussion about technical editors. One thread debated whether editors should be responsible for checking facts, or testing the document against the product, or doing a variety of jobs that I (and many editors) consider to be an appropriate and important part of a technical editor's role (in contrast to a copy-editor's role), but some members of the list appear to think otherwise.

Here is one note that puts an important point of view that no one else had covered up to that point. It is published here with the permission of the author, Rick Lippincott RJLippincott@compuserve.com, who makes a very good point about the perception of what people do, based on their job titles, and how that perception can confuse what an editor's role can, or should, actually be.

--------
I think ... that we're looking at this from the wrong angle. We're talking about a "technical editor." The image this gives to me is a person who sits at a desk, reviews the copy, and (supposedly) marks up the technical errors. An editor who is concerned with technical accuracy.

The problem is, the quest for technical accuracy shouldn't be left to a person called an "editor." You really need an entirely separate role, with an entirely separate name. Take the word "editor" out of it so that there's no confusion or expectation that the person is expected to do any type of language or style checks.

What you are actually seeking is a separate position, one that I call a "validator." The validator won't be looking at spelling, grammar, or style. The editor won't be looking at technical accuracy.

The validator's role in the process is to take the draft copy, and perform a set of specific, clearly defined tests to ensure that the procedures work as written. In the case of software procedures, the validator logs onto a test system and actually runs through the procedures. In the case of hardware procedures, the validator gets access to the hardware and the necessary tools, and physically does the procedures. This is known as "validation by demonstration."

Validation by demonstration should make up the bulk of all the testing done on the docs.

In some unique hardware cases, it may not be possible to do tasks such as component removal and installation, but a detailed, on-site thorough examination coupled with a step-by- step review of the procedure can often serve to confirm the accuracy of the procedure. This is known as "validation by simulation."

And in some hardware cases, items such as tolerances, inspection limits, and repair methods might be best determined by a line-by-line review against the original engineering data (the blueprints). This is known as "validation by comparison."

On completion of the validation, the writer gets back a series of clear, specific, and detailed review comments for incorporation into the text. If the validator has a background in technical communication (which is ideal), there is a reasonable assurance that the comments will be in fairly good shape regarding style, format, grammar, spelling, and the like.

This is actually a concept that I've done for a number of years, and introduced with some success at two companies. I'm actually surprised that it hasn't been more widely adopted. From my experience, it's the best way to ensure that the docs work as written.

The key difference between the technical editor and the validator is that there is an implication (at least because of the name) that a technical editor will mainly work at a desk, conducting a passive review. A validator, on the other hand, is a more active reviewer, with more hands-on involvement and physical participation in the process.

Back to top

---

Paramedic method of editing

Recently someone asked the Australian editors' list about the "paramedic method of editing". I had never heard this term before, so I took a guess (which turned out to be wrong), but fortunately someone else on the list went to the trouble to look it up on Google. Here is what she found:

"According to one article, the 'Paramedic Method' involves bringing writing that lacks vitality back to life. It then offers an 8-step process for achieving this. If anybody is interested, here's the link: http://ronscheer.com/html/readingroom13.html.

"Apparently, the 'method' can also be found in Revising Prose by Richard Lanham (MacMillan NY, 1987)."

Here was my guess:
"I've never heard this term used, but I would assume it has something to do with triage: if you have limited time available for either editing or rewriting, you divide the changes into three categories:

1. Changes that must be made because content is factually incorrect or the wording is unclear or ambiguous and may lead to serious misunderstanding, or changes that are required for legal reasons.
2. Changes that improve the writing or presentation but are not essential to understanding.
3. Changes that others might consider pedantic nitpicking, and that the vast majority of the audience won't care about or probably even notice."

Lastly, here is someone else's guess:
"I have never heard of the term either, but to take [Jean's] analogy further I am under the impression that in the U.S. the paramedics arrive first at the scene of an accident, like Australian ambulance officers, so perhaps they are referring to a quick first-aid edit on the spot; life-saving in an emergency, but not deep, time-consuming reconstructive surgery?"

Back to top

---

"Use cases" and "user scenarios" explained

In January 2000 I sent a message to the TECHWR-L and WINHLP-L asking for a "plain English" explanation of use cases and user scenarios, as used in designing, programming and documenting software applications. I compiled a file of the responses I got, which was posted on the Techwhirl website for awhile but was removed during a reorganisation of the site.

I have now posted the file on my own website. http://www.jeanweber.com/howto/usecase.htm

Back to top

---

Book: Promote Your Business, by Mary Morel

(How to write effective marketing material for your small business), Allen & Unwin, 2003, ISBN 1865089311

I recommend this book as an excellent, concise, easy-to-read summary of what you need to do, and how, to market yourself and your business. Mary's use of three example companies throughout the book is a great aid to understanding the concepts she describes, by seeing how they can be put into practice. For me, the book was a good refresher course on techniques that I knew about in the abstract but had never really put into practice. I was motivated to start immediately on improving -- and implementing -- my marketing plan.

Topics covered include:

1. How to write a business and marketing plan
2. Branding and creating visual impact
3. Writing guidelines
4. How to write brochures and flyers
5. How to write a press release
6. How to write direct mail
7. How to write an advertisement
8. How to write your website
9. How to write newsletters and ezines

If you aren't in Australia, you can still order this book from the Allen & Unwin website or through Mary's own website, http://www.themfactor.com.au/.

Back to top

---

Book: Google Pocket Guide, by Tara Calishain and others

Published by O'Reilly, 2003, ISBN 0596005504.

Buy it through my Amazon link!

Last issue I mentioned Google Hacks, by the same authors. Now O'Reilly has published a short version as part of its Pocket Guide Series. This book is intended for people like me who mainly want to improve their searching technique and better understand the results Google provides, but aren't interested in uses of the API or external applications.

This smaller, cheaper version may suit your needs, if the heavy-duty hackers' version is a bit too much. Both contain good, solid information that should be valuable to everyone who uses Google. Recommended.

Back to top

---

UCLA Extension online Technical Communication courses

Courses for the summer quarter begin in July 2003.

Courses offered this Summer include:

• Information Design
• Technical Writing
• Technical Editing
• Creating Readable Documents
• Introduction to Project Management
• Managing Effective Proposals

Fees are US$500 to US$550 per course, with a $50 discount for STC members. For more information, please visit http://www.uclaextension.org/businessandmanagement/.

Or contact:
Helen Williams
UCLA Extension Program Representative
hwilliam@unex.ucla.edu

Back to top

---

For Australians: National Editors' Conference 17-20 July 2003

Bardon Centre, Brisbane, 17-20 July 2003.

Council of Australian Societies of Editors (CASE) presents "Beyond Gutenberg and Gates... gazing into the e-future" -- the first Australian national conference for editors, by editors ... an opportunity to explore the major issues that confront our profession in the 21st century, including:

• the changing nature of our profession
• editing standards and accreditation
• promoting the profession and marketing your editing services

The conference will be of interest also to authors, publishers, designers, academics, information managers and others engaged in the profession of editing for publication.

For additional information, including a full conference program, write to:
The Society of Editors (Queensland) Inc.
National Editors Conference
PO Box 1524
Toowong Qld 4066
email: Robin Bennett on beyondgutenberg@hotmail.com
or June Kant on ihpa@mailbox.uq.edu.au
or look at http://www.editorsqld.com/

Back to top

---

For Australians: Technical and Scientific Editing Workshop, 23 August 2003

The Society of Editors (NSW) is holding a workshop on technical and scientific editing.
Saturday 23 August, 9 am to 5.30 pm
Sydney Room, Level 2, City Tattersalls Club, 198 Pitt Street, Sydney (between Market and Park streets)
Cost: $145 members of the Society of Editors and others (includes lunch, morning and afternoon tea)

Enquiries to Pauline Waugh, paulinewaugh@ozemail.com.au
or Julie Stanton, juliestan@bigpond.com.
Bookings to Society of Editors (NSW), PO Box 254, Broadway NSW 2007, by Friday 15 August 2003.

This workshop will be useful to those already working on scientific or technical publications-including books, journals, journal articles or monographs. It will also be useful to editors working in other fields who would like to expand their skills.

Speakers and topics:
Jill Nicholson, "Editing technical writing--why is this different?"
Rhana Pike, "Illustrations and tables in scientific publications"
Matthew Stevens, "Substantive editing of scientific work"
Bruce Howarth, "Editing and managing references"

Back to top

---

My books: Taming Microsoft Word and others

Taming OpenOffice.org Writer, http://www.taming-openoffice-org.com/writer/towtoc.htm
Taming Microsoft Word (3 editions, for Word 2002, 2000, and 97), http://www.jeanweber.com/books/tmw
Editing Online Help, http://www.jeanweber.com/books/olhbk.htm
Electronic Editing, http://www.jeanweber.com/books/e-edit.htm

---

© Copyright 2003, 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.

---