The Technical Editors' Eyrie Newsletter

Issue 33, 19 March 2000

ISSN 1442-8652

Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com

In this issue...

Feature article: What is substantive editing?
Comment: There's more to it than grammar
Technical Editors' Eyrie website now has search capability
STC Pan-Pacific conference
University courses in Australia related to technical writing and editing
Resource: Windows interface guidelines for software design
The latest on Mastering FrameMaker 5 reprint
Subscription information

Feature article: What is substantive editing?

Moved to http://www.jeanweber.com/howto/substant.htm.

Comment: There's more to it than grammar

by John Wilson jwilson@AMADEUS.NET

[Editor's note: This article is closely related to the previous article on substantive editing. It is slightly modified from a note posted to the Techwriters' list, TECHWR-L, in March 1999, and is used with the author's permission.

Although John is primarily talking about technical writers, his comments apply equally to technical editors, and with minor modifications to editors in any field. You may find it useful when negotiating with writers and other clients, if they want to know why you're so "picky" about certain topics, or who claim that grammar isn't important.]

I think a number of misconceptions about our business are widespread in our profession.

Grammar. ... grammar is not an add-on, or a set of arbitrary rules. Some usage is arbitrary, but grammar is a method of ensuring that discourse is coherent. Grammar is to a large extent hard-wired in our brains. Stephen Pinker ("The Language Instinct") and others have written books on this topic. Yes, some usages (like its and it's) are unpredictable and we just have to learn them.
Style Guides. Style guides often attempt to ensure a number of things which in my view are quite distinct from each other:
1. that company documents all look similar, to reassure the reader
2. that the terminology used is relatively consistent so the reader doesn't have to guess when window=screen=box, for example
3. that the non-technical words used are understandable by the reader ("that is" instead of "i.e." for example)
But there is a lot more to it than style. A style guide will not instruct writers in general word use, or in the analysis of a problem.
Technical writers themselves (and many books which are allegedly about technical communication) spend time discussing grammar, style and usage rather than analysis, logical sequence of information and other vital elements. I think this is because it takes a lot less thought and effort to spot grammatical errors on a page than it does to check for usability errors in a product, or structural errors in a manual. (Just as employers use lists of software tools, rather than writing ability, to select writers - it's easier.)
Grammar and style are necessary but ... a long way from being sufficient for producing good manuals. What else is required? This is the question which a few people have asked (what do technical writers do?) but which almost nobody has tried to answer.

In my view, our lack of clarity on this question is a large part of the reason for the low status that many writers complain of. "Perception is all there is" - whatever you may actually be doing, if all you draw attention to is grammar, engineers and managers will perceive you as a grammar checker. However, if you ask questions about what the product is for, what the user's expertise and motivations are and so on, you might be perceived as something more. But this indispensable part of a technical writing or communication project - analysis and specification like in any other engineering work - gets little attention in this list.

A technical writer does not just write manuals. The job title is established by usage and should not be taken literally. A technical writer in this day and age must be someone who tries to make a product usable. Manuals may or may not be a means of doing this. How does the writer go about making the product usable? What service are you offering? What do technical writers do?

Technical Editors' Eyrie website now has search capability

I've added a search capability to my website. It's powered by AtomZ, a free service that provides a lot of flexibility yet doesn't clutter the page with advertising.

To search my site, look for the search box on the first page of the site, or click on "Search this site" in the left-hand column of any of the main pages. That will take you to a page where you can choose either a simple search or an advanced search.

If you're interested in the AtomZ search service, here's the address: http://www.atomz.com/

Note: I have no affiliation or association with AtomZ.

STC Pan-Pacific conference

Bonni Graham bgraham@manuallabour.com writes,

The 2000 Society for Technical Communication (STC) Pan-Pacific conference is being held this year in Hawaii on October 19-21.

Visit their web site for more information, including general conference and registration information, and much more: http://www.pan-pacific.org (October 2001: address no longer valid.)

The organisers hope the location will encourage international professionals from all Pacific Rim countries to come and share their experiences.

University courses in Australia related to technical writing and editing

This information has been moved to http://www.jeanweber.com/links/auscours.htm.

Resource: Windows interface guidelines for software design

The online version of Microsoft's hardcopy book "The Windows Interface Guidelines for Software Design" starts here: http://msdn.microsoft.com/library/books/winguide/welcome.htm

These guidelines can be quite useful when editing software interfaces or user guides for software, among other things. Chapter 12 on "User Assistance" is particularly relevant to editors of online help.

(October 2001: the address given above is no longer valid, and I could not find this document on the Microsoft site. It may be still there, just very well hidden.)

The latest on Mastering FrameMaker 5 reprint

This item is now out of date and is here only for archival purposes.

Thomas Neuburger thomasn@twelfthnight.com writes,

Two exciting pieces of news--online ordering and the schedule for actual books.

Online Ordering -- For those of you who prefer to order online by credit card, go to the FrameUser's website: http://www.FrameUsers.com
and click the link for Mastering FrameMaker: http://www.FrameUsers.com/masteringframemaker.shtml

Then fill out the form and click Submit. This information runs on a secure server. Assuming that the first run is not exhausted (so far no problem), books will be shipped as soon as the credit information is verified.

Book Schedule -- The printer is running one more proof today [8 March], which will be checked by the marketing manager against my short list of corrections. He'll then try to get us into the print schedule for this Friday (March 10).

If so, I'll have books in hand next week and will start mailing immediately to those of you who have sent orders.

Contributors wanted

I'm looking for people to contribute some articles, or tips, or short notes about almost anything related to editing, to this newsletter. If you have something relevant to share, please send it to me! I'm sure the readers would appreciate some contributions about different working styles, materials and clients.

Advertisement: Electronic editing book

Electronic editing: Editing in the computer age
by Jean Hollis Weber
Published by WeberWoman's Wrevenge
248 pages
ISBN 0646380370

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.

Available in both downloadable electronic (PDF) and printed forms. For details on ordering a copy, see
http://www.jeanweber.com/books/e-edit.htm#order

or send e-mail to e-edit@jeanweber.com

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.

Articles © Copyright by their authors.
© Copyright Jean Hollis Weber, Technical Editing Consultant
WeberWoman's Wrevenge, Airlie Beach, Qld., Australia, jean@jeanweber.com
ABN 18 005 740 467

Last updated 26 September 2002