Issue 28, 13 December 1999
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
Have you had trouble downloading, printing, or paying for my book?
Advertisement: Electronic editing book
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.
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!
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
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.
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,
- " 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. "
- 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.
- 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
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. "
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.
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!
Electronic editing: Editing in the computer age
by Jean Hollis Weber
Published by WeberWoman's Wrevenge
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
or send e-mail to email@example.com
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.
© Copyright 1999, 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.
This newsletter is no longer being published.
I do not sell, rent, or give my mailing list to anyone.