Using Contractions in Software Manuals

Subject: Using Contractions in Software Manuals
From: VSOL - Victor Solano <VSOL -at- SBT -dot- COM>
Date: Tue, 11 May 1999 09:19:41 -0700

I write for a company that produces accounting software. Our manager thinks
that we should avoid contractions, but the writers beg to differ. Read on.

This is an e-mail our manager wrote to the Franklin Covey Style Guide:

We create documentation to support Accounting Software. Previous writers of
our documentation were quite liberal in their use of contractions. I am of
the opinion that contractions are inappropriate in software manuals.

Your Style Guide for Business and Technical Communication states as follows:

"Contractions are not appropriate for very formal or ceremonial documents
such as contracts or legal notices. However, contractions lead to a
conversational, friendly tone in most other business correspondence."

What is your stand on the use of contractions in software manuals?

The Franklin Covey Response:

Your question was forwarded to me yesterday. I remember my seventh-grade
English teacher threatening to mark us down a letter grade for each
contraction used in a paper. So I learned at an early age.
Having said that, there are, of course, exceptions. Because our products
are built around a time-management process that should be very personal to
each user, it is often easier to write about issues and topics in a more
informal/conversational manner. This causes us to break style occasionally
(which may or may not include a contraction), but only if it more accurately
conveys the meaning of the text. However, if you are looking for my opinion
and what how I would instruct new writers, it would be to avoid contractions
like the plague.

The response from a senior writer in our department:

My guess is that [this writer] was in the seventh grade before 1970, or did
not go to a public school.

(Woe is I, The Grammarphobe's Guide to Better English in Plain English by
Patricia T. O'Conner - the book you bought in Seattle - has yet another
opinion.)

I think, in general, contraction avoidance is somewhat outdated. I don't
think our documentation requires the kind of formality ("very formal or
ceremonial documents such as contracts or legal notices...") implied by
entirely avoiding 'em, and I don't think getting rid of contractions in
existing doc represents a valuable change or a meaningful use of our time.

If the doc already wasn't using 'em, I might go along with continuing
thusly, but I just don't see a compelling reason to spend any time getting
rid of 'em, or even crossing the street to get out of their way.

In some cases, I like contractions better than their 'detractions.' E.g., I
personally prefer "can't" to "can not" or "cannot" -- it's quicker, and
everyone knows what it means. Others, I don't like as much. Julie made the
very good point a while ago that we probably shouldn't use 'em in cautions.

However, we should watch for and eradicate contractions that mask passive
voice and non-present-tense ("you've," "you'll"), which we do want to avoid.
Usually, when you rewrite these, the sentence ends up shorter than it was.

Maybe we should start adding particular contractions that we'd like to avoid
to the DUD list, but I don't agree with slashing and burning through the doc
just to sound like a seventh-grade English teacher.


Any comments, suggestions? What is the general consensus on usage of
contractions in software manuals?

******************************************************
Victor Solano
SBT Accounting Systems
Technical Writer / Technical Publications Dept.
1401 Los Gamos Drive
San Rafael, CA 94903
(415) 444-9807
vsol -at- sbt -dot- com
******************************************************


From ??? -at- ??? Sun Jan 00 00:00:00 0000=



Previous by Author: Re: proper name for a toolbar button
Next by Author: Re: Using Contractions in Software Manuals
Previous by Thread: Re: ownership rights
Next by Thread: Re: Using Contractions in Software Manuals


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads