Newsletter
Newsletter Issue 50, 17 August 2001
ISSN 1442-8652
Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com
In this issue...
News from the Eyrie
Possessives in technical writing?
Ethics in scientific and technical communication
Stressing what is important in a sentence
Editing tables
Analysing a document and developing an editing plan
How to remove files from Microsoft Word's Work menu
Books available from Jean Hollis Weber
Taming Microsoft Word
Editing Online Help
Electronic Editing
Subscription information
News from the Eyrie
I'm back early from a very successful and enjoyable trip to Lake Eyre, South
Australia. If you're interested, the first two installments of the trip report
are online, and more are coming.
http://www.avalook.com.au/newsletr/oznews24.htm
http://www.avalook.com.au/newsletr/oznews25.htm
With so many new subscribers having joined in the last six months, I've decided to draw your attention to some articles from earlier issues by reprinting parts of them, in addition to this month's new material.
Did anyone notice that last month's newsletter was numbered 48, when it should have been 49? (The real number 48 was published in March.) No? Neither did I, until I started work on this issue. I have corrected the number on the Web copy.
As always, I welcome contributions from readers. Do you have some tips, insights, or resources to share?
Possessives in technical writing?
Last month a brief debate erupted on TECHWR-L about possessives - are they appropriate in technical communication?
The ever-sensible Geoff Hart ghart@videotron.ca responded,
"It's not a rule; it's a style choice, and probably a bad one for competent writers to use as standard operating procedure. The reasons I've seen given to justify this rule include:
- The fact that using a possessive can be seen to personify something inanimate:
anthropomorphizing is a bad idea in general, but inadvertently doing so
only becomes a risk you're careless with your possessives.
- The risk of confusing translators: any translator who doesn't know how
possessives are formed in English should find another profession. Of course,
if you (as the writer) don't know the difference between its and it's, then
yes, you're going to confuse everyone, and should avoid possessives.
- "That's the way it's always been done": some old Thistlebottoms feel uncomfortable attributing a possessive to anything inanimate, despite the lack of any grammatical justification for this opinion.
"About the only good reason to avoid possessives is the risk of confusing a reader with poor English skills (e.g., someone whose native language isn't English, or a low-literacy audience), but even then, the problem only arises if you're sloppy about clearly attributing the possessive to the right object.
"You can certainly write around this by using genitives (e.g., the Word menus rather than Word's menus), but that's not necessary in most cases. So on the whole, it's not a guideline you really need to follow. Moreover, careful use of possessive makes your writing seem more fluent and idiomatic, and that can be a very good thing indeed for most audiences."
My comment on the subject:
A practical reason for not using possessives is that so many people these
days don't know how to use an apostrophe correctly. "Real" techwriters should
(and usually do) use them correctly; but as we all know, a lot of techwriting
is done by other people who don't get it right - and don't have the benefit
of an editor to fix their punctuation errors. I can easily see a company (or
a style guide) that forbids possessives for this reason, even though the reason
isn't stated; later the rule is remembered as a more general one ("not appropriate
in technical writing").
Ethics in scientific and technical communication
In 1995, I wote an article about ethics in scientific and technical communication. The article is a brief summary of some general categories of ethical issues, which editors as well as writers need to consider:
- Knowing and doing - taking personal responsibility for one's actions
- Legal and ethical are not synonymous
- Behaviour toward colleagues, subordinates and others
- Dealing with experimental subjects, interviewees, etc.
- Telling the "truth"
- Rhetoric - choosing your words
- How much detail is appropriate?
- Choosing between advocacy and objectivity
The full article is at http://www.jeanweber.com/about/ethics.htm
Stressing what is important in a sentence
Reprinted from Issue 7, 6 May 1999, http://www.jeanweber.com/news/tenews7.htm
In addition to expunging the usual collection of wordy phrases from documents, editors commonly attempt to tighten up writing to make it more direct, clear, and concise. For example, when editing business and technical material, I frequently change sentences containing "it is", "there is", and "there are". Writers often ask me, "What was wrong with that sentence?" I reply that although the sentence wasn't wrong grammatically, such phrases distract the reader from the important part of the message.
Examples
Many of these examples contain other wording that can also be improved, and some could be rewritten more elegantly in context, by changing other sentences as well as these. See the original article for more examples.
No: There is a fee of $150 for this course.
Yes:: The fee for this course is $150.
No: There are some pre-requisite activities that
need to be undertaken.
Yes:: Some pre-requisite activities need to be
undertaken.
Better: (Choose one that fits the circumstances)
We need to undertake some pre-requisite activities.
(or) The client needs to undertake some pre-requisite activities.
(or) You need to undertake some pre-requisite activities.
No: If there is more than one enrolled user for
the account, see...
Yes:: If more than one user is enrolled for the
account, see...
No: There are three main areas available for data
storage: (followed by bullet points)
Yes:: Three main areas are available for data storage:
No: Tours will be arranged so there is no interruption
to normal system maintenance or testing procedures.
Yes:: Tours will be arranged to avoid interruption
...
(or, depending on context) Arrange tours to avoid interruption...
(or) We will arrange tours to avoid interruption...
No: There are a number of reasons for this decision:
(followed by several bullet points)
Yes:: The reasons for this decision are:
No: It is difficult to package equipment for transportation.
Yes:: Packaging equipment for transportation is
difficult.
No: It was easy to learn the new procedures.
Yes:: Learning the new procedures was easy.
(or) Users learned the new procedures easily.
You get the idea. There examples were not difficult to change, but some other uses of "there is," "there are" and "it is" are more complicated to fix; changes usually involve rewriting more than the sentence in which they appear.
Editing tables
Reprinted from issue 9, 20 May 1999, http://www.jeanweber.com/news/tenews9.htm
Tables can be used for different purposes. The most common purpose is to present numerical data. Other data may be in the form of words, phrases or sentences.
Some things to look for when editing tables:
- Is there too much data? If so, is all of the data needed? Can the table
be divided into more than one table? Can a summary be put into the main
body of the document, and the details into an appendix? Can some of the
information (such as explanations) be put into table footnotes?
- Does the information in the table duplicate information in an illustration?
If so, is this needed or helpful to the reader? Perhaps one could be cut
out.
- Columns are better than rows for comparisons. Does the table need to be
reorganised?
- Does the table need a caption? Some short tables may not, but major tables
should have captions. Is the caption informative? It should usually be short,
leaving extended discussion to the text.
- Are the column and row headings brief, but easy to understand?
- If the table is complex, can it be made easier to follow by using main headings and subheadings for the columns and/or rows?
Editing statistical tables
Instead of repeating an entire paper in this newsletter, I have placed it on the Web site.
Please see "Editing tables of data" by Irene Wong, for an excellent summary of things to look for when editing statistical tables: http://www.jeanweber.com/howto/ed-table.htm
Analysing a document and developing an editing plan
Reprinted from "Deciding what needs to be done", Issue 11, 3 June 1999, http://www.jeanweber.com/news/tenews11.htm
Before you begin editing a document, you need to analyse it and plan what needs to be done. The exception is when your job is strictly limited (by your supervisor or the client) to correcting only the glaring errors of spelling, punctuation and grammar (a "light edit"). There is no point to attempting a more substantive edit if doing so will only get you into trouble (or if the client won't pay you for the time you spend).
If your job is less defined, or if (during the light edit) you see that the document seriously needs restructuring or rewriting, you need to determine what needs to be done and then get approval to do the work. You may need to exercise considerable tact when presenting your plan to the author or other person who must approve your proposal.
In some cases, your job is defined as one of restructuring and rewriting as necessary, so you may not need to seek approval -- but you should still plan your work before starting. You may find that you cannot possibly do everything that needs to be done in the time available, so you will also need to prioritise your work.
Timing is important
Substantive editing (also known as developmental or comprehensive editing) should be done during the draft phase of writing the document, usually before page layout.
If someone comes to you with a document that's ready to go to the printer and asks (or tells) you to edit it, you may not have time for a restructure or rewrite even if the document desperately needs it. The best you can do in this situation is to point out (as tactfully as possible) some of the major problems and hope that someone will authorise delaying printing until the problems can be fixed. You may also wish to ensure that the author's instructions to you (for a light edit) and your evaluation (that a heavy edit is needed) are put in writing.
Steps to follow when developing an editing plan
Carolyn Rude (Technical Editing, 1998) gives four steps to follow when developing an editing plan for a document:
- Analyse the document's readers, purpose, and uses to determine what the
document should do and the ways it will be used.
- Evaluate the document's content, organisation, visual design and style
to determine whether the document accomplishes what it should. Don't get
bogged down in design details at this point, especially if the document
hasn't been through page layout yet.
- Establish editing objectives to set forth a specific plan for editing.
Make a list of what needs to be done. Prioritise the list in preparation
for step 4.
- Review the plan with the writer or client, to work toward agreement on how much editing to do. Once you have established the editing plan, you are ready to edit.
You can read the full article at http://www.jeanweber.com/news/tenews11.htm
How to remove files from Microsoft Word's Work menu
Last issue I enthused about Microsoft Word's Work menu, without having used it much myself. Several people wrote to ask how to remove files from the menu, and I was chagrined to discover that I couldn't figure out how to do it either.
Daniela Meleo passed on to me the solution, gleaned from the archives of the WORD-PC list:
- Press Ctrl+Alt+Hyphen. The pointer turns into a little horizontal black bar.
- Click on the item you want to remove.
It's an obscure and clunky method, but it works.
Books available from Jean Hollis Weber
Taming Microsoft Word
116 pages
ISBN 0 9578419 2 2
Published February 2001
A quick reference for writers, editors, and others who need to use some of Word's more advanced features. This book is an expanded and updated version of Chapters 3 and 4 in my first book, Electronic Editing. Taming Microsoft Word is quick to read, yet packed with essential information.
A full contents list and information on downloading the PDF file and paying for it are available here: http://www.jeanweber.com/books/tameword.htm
Editing Online Help
155 pages
ISBN 0 9578419 0 6
Published October 2000
For students, writers, and editors who are developing online help for computer software, and for their managers and clients.
Supplements tool-specific instruction by presenting the basics of help content development, regardless of the operating system running the application, the type of help being produced, or the tools used to produce it.
More information here: http://www.jeanweber.com/books/olhbk.htm
Electronic Editing
248 pages
ISBN 0 646 38037 0
Published October 1999
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.
More information here: http://www.jeanweber.com/books/e-edit.htm
© Copyright 2001, 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.
Home | About | Books | How to | Links | Newsletter | Business | Site index | Search
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
