The Technical Editors' Eyrie Newsletter

Issue 28, 13 December 1999

ISSN 1442-8652

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

In this issue...

Chapter 1 of Editing Online Help now available for comment
Be wary of seasons and holidays
Plain English, anyone?
Why be so picky?
Some articles on editing and style guides
Contributors wanted
Have you had trouble downloading, printing, or paying for my book?
Advertisement: Electronic editing book
Advertising policy
Subscription information

Chapter 1 of Editing Online Help now available for comment

In the last two issues of this newsletter, I had published excerpts from an early draft of the first chapter in a book I'm writing on editing online help.

This book was published in October 2000. See link in left-hand column.

Be wary of seasons and holidays

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

Plain English, anyone?

Here's a sample I pulled out of my files recently. This was a set of "reason codes" for programming and writing errors. I'm not sure who originally wrote it, but the rewrite was done by one of the software developers, not a writer. I thought he did a great job!

Original version

OV Oversight - Failure to consider all cases and conditions

ED Education - Lack of understanding of some aspect of the product, application or process

CO Communication - Absence of, or incorrect information

TR Transcription - Error in interpretation

PR Process - Problem with the development process (including the quality process)

Plain English version

OV Did not think of it

ED Did not know at the time

CO Was not told about that

TR Read it incorrectly

PR Slipped through undetected

Why be so picky?

You know, and I know, why editors are so picky, but sometimes we have to explain our work to writers, managers and others. I hope you might find these notes useful. I wrote them for a talk to a class of engineering students.

Anything that interferes with your message should be avoided.
Accuracy in language can be as important as accuracy in technical details.
Poor grammar or ambiguous phrasing can obscure what you are saying; this can have major consequences, for example in instructions or procedures.
If your work contains incorrect spelling and grammar, and inconsistencies in terminology and presentation, the reader might think your technical work is also incorrect.
If several people are working on a document, they often use different words for the same thing, or present similar materials in quite different ways. This can confuse the reader. Collaborative work should look as if it were done by one person.

Some articles on editing and style guides

These articles appeared in Technical Communication, the journal of the Society for Technical Communication. The descriptions are the abstracts or executive summaries from each paper, or in some cases extracted from the discussion or conclusions of the paper.

Gerich, Carol, "How technical editors enrich the revision process," TC 41 (1), pp. 59-70, 1994.

" Revision, as practiced at a major scientific R&D laboratory, is collaborative -- teaming scientific authors, technical editors, colleague reviewers, and supervisors -- to ensure more papers are accepted by prestigious journals. As shown in this case study, this collaborative approach works effectively for authors and enhances the role of editors. As team members, editors are encouraged to provide substantive, not merely cleanup or surface, revision. Their three main responsibilities reflect what research adveses are the three primary skills of expert writers: detect problems, diagnose their causes, and determine strtegies to fix them. To be the most effective revisers, however, editors must be involved earlier in the collaborative review process. Their precise entry point depends on the type of writing: The more complex and collaborative the document, the earlier editors should become part of the review team. As a general rule, editors should be involved at the same time as colleague reviewers. "

Hauge, Diane, "Editors, rules, and revision research," TC 38 (1), pp 57-64, 1991.

" A review of the research literature shows that academics and practicing editors do not share the same view of the editing process: The academics emphasize "intentional diagnoses," and the practitioners perform "rule-based" editing. However, the differences conceal similarities, and practicing editors could profit from what academics have learned about the writing process: The editor can be of most service to the author by becoming involved in the writing process itself. "

[My comment: I think editing (at least from the editor's point of view) has come a long way since the literature surveyed in this article, but my experience suggests that most of the people we work with still think editors only do rule-based editing. -- Jean]

Speck, Bruce W., "Editorial authority in the author-editor relationship," TC, 38 (3), pp. 300-315, 1991.

" The literature on editing over the past four decades presents three conflicting views: that the author is the final authority; that the author is incompetent and needs help; and that the editor has final authority. Editors use four rhetorical strategies to establish their authority: They use editorial dialogue, define the audience, cite authority, and teach. This article classifies editors as high- or low-status instead of the usual literary vs. technical division and explains how they use the four rhetorical strategies to achieve their documentation purposes and gain auctorial respect. "

Allen, Paul R., "User attitudes toward corporate style guides: a survey," TC 43 (3), pp. 237-243, 1996.

" Little information is known on user attitudes toward corporate styles guides (CSGs). A national survey shows that an overwhelming 93% of users and 85% of non-users advocate CSG usage primarily to generate consistency in documents, to save time generating documents, and to create a professional look in documents. As corporations face the future by restructuring, usually by downsizing, and by competing more in a global economy, CSG usage will be more prevalent in corporate America, as the results of this survey indicate that CSGs are an economical quality tool that benefits both the user and the corporation. "

Allen, Paul R., "Save money with a corporate style guide," TC 42 (2), pp. 284-289, 1995.

" A corporate style guide can help today's writers, who are often pressed for time to do the best job possible. Because of the quick turnarounds required, the frequency of corporate reorganizations, and the proliferation of interruptions, the quality of many documents suffers. Corporate style guides can improve document quality by: creating consistency within and among documents; promoting a professional image; training new employees; and defining document generation. These style guides provide big dividends for a small investment. "

Nadziejka, David E., "Needed: A revision of the lowest level of editing," TC 42 (2), pp. 278-283, 1995.

" Most levels of editing systems provide obvious benefits to the technical editor, but they are structured to treat the author's main concern -- the content of technical documents -- only at the higher levels. This article discusses why a system so structured is increasingly untenable, and a revision of the lowest level of editing is proposed to address the issues of primary concern to all three major parties in producing a publication: the organization, the author, and the technical editor. "

...three areas ... demand priority in a rapid-turnaround situation. The first area of priority ... is essentially the "policy edit" ... does the document meet organizational requirements for publication? [this is] ... concerned with ... copyright, libel, and endorsement or advocacy statements ... The second area of priority ... develops directly from the need to skim the manuscript for policy concerns... the editor ... may as well mark the spelling errors [etc. that] are easily noticed... The third area [is] protecting the author's interests. [This should involve the editor in at least three tasks:

Read the abstract, the introduction, and the conclusion to ensure that they are not contradictory. Edit any prose in these sections that is ambiguous or incomprehensible and query the author if necessary.
Read the text around the callouts to figures or tables and ensure that the text statements agree with the values in the tables or with what is shown in the figures; call the author's attention to any discrepancies.
Read any paragraph of text that appears to summarize or state results and ensure that these statements do not contradict the abstract or conclusion sections; again, call the author's attention to any discrepancies. "

Mackay, Peter D., "Establishing a corporate style guide: A bibliographic essay," TC 44 (3), pp. 244-251, 1997.

" Surveys articles and conference presentations on style guides published between 1985 and 1995. Analyzes significance and contribution of each. Suggests areas for further research, specifically quantitative analysis of the value of style guides. "

From the conclusion to the paper:
" The current research makes clear that developing an effective house style guide requires much detailed planning. One must assess the organization's needs and sometimes juggle the expectations of management and staff... It is also necessary to recognize at the outset what a house style guide can and cannot accomplish... the general consensus of the authors analyzed here seems to be that a carefully planned style guide is well worth the effort required to produce it. "

Caernarven-Smith, Patricia, "Aren't you glad you have a style guide? Don't you wish everybody did?" TC 38 (1), pp. 140-142, 1991.

" The purpose of your style guide is to help you to produce a high-quality publication... Style guides work well if they are comprehensive and simple to follow, and if they anticipate problems... An alternative to the style guide is the template ... While useful, templates do not assure the same quality as style guides... "

Discusses some reasons why style guides are a management issue, in particular in minimizing time-wasting arguments over style. "... a style guide is a productivity tool, saving time and money, as well as a quality tool. "

Nichols, Michelle Corbin, "Using style guidelines to create consistent online information," TC 41 (3), pp. 432-438, 1994.

" This article examines the research behind the use of style guidelines to create consistent online information. ... from research on screen design, schemata, and reader styles, it offers a specific set of style guidelines. Consistency is the key design principle for all online information, and style guidelines are the way to achieve that... "

The screen-design principles described are that online help facilities should be easy to access, structured with different levels, specific to the situation, concise and easily browsed. Although some of the details reflect the types of online information available when the paper was written, the principles and examples are still valid today.

Washington, Durthy A., "Creating the corporate style guide: Process and product," TC 40 (3), pp. 505-510, 1993.

" A style guide creates and defines the standards for corporate documents and helps establish a consistency among these documents that reflects a company's commitment to quality and style... Its primary function is to streamline the document development process and thus significantly reduce the time required to create new information products. But an effective style guide can also serve as a training tool for new writers, editors, and documentation managers...

This article describes the elements of an effective style guide [and] presents methods and techniques required to develop a style guide tailored to meet the specific needs of an organization... "

[My comment: The author includes (in the content list for a style guide) several topics that I think should be in a different document, such as a process guide. -- Jean]

Washington, Durthy A., "Developing a corporate style guide: Pitfalls and panaceas," TC 38 (4), pp. 553-555, 1991.

" This paper describes the potential problems and frustrations -- as well as the rewards and challenges -- inherent in creating an effective style guide. "

Contributors wanted

You've probably noticed that this issue is over a week late. I'm getting organised for another round of major life changes. (If you're interested, you can see what I'm up to at http://www.avalook.com.au/ -- especially the links to the aboutus and motorhome pages.)

Although part of my efforts involve clearing out numerous boxes of notes (which I've been turning into articles for this newsletter, among other purposes), I'm not finding much time to make order out of those notes.

So... if anyone would like to contribute some articles, or tips, or short notes about almost anything related to editing, please send them to me! I can make time to organise material into a newsletter -- it's only the writing that takes too much thought just now.

Besides, I'm sure there are lots of you who have ideas and resources to share that are at least as good as mine, if not better -- and certainly representing different working styles, materials and clients.

Have you had trouble downloading, printing, or paying for my book?

If so, please let me know so I can attempt to do something about the problem. Two people have mentioned problems printing the PDF from a Macintosh, but I don't know enough details to decide whether it's a general problem or not. If you have successfully printed part or all of the PDF from a Mac, please let me know!

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

Advertising policy

If you have a product or service of interest to editors, I'll be happy to consider including a short advertisement, for a modest fee. Contact me for details.

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 3 June 2002