April 11, 2011
|
Contractions
|
36453 hit(s)
One way to change the tone of your documentation is to use — or not use — contractions.[1] The Microsoft style guide leaves it up to individual teams to decide whether to use them, but offers some guidance (I paraphrase):
 - Readability studies suggest that contractions are harder to parse then non-contracted phrases.
- Contractions can be harder for ESL readers to process.
(Plus some details about when not to contract, such as combining a noun and verb: "the program'll stop" is disrecommended.)
Our divisional style guide (developer documentation) is less laissez faire about this: "Do not use contractions." (Extra points for the meta-usage.)
Ok. So, as I noted sometime ago, when we launched one of our more recent projects, there was a conscious effort to "friendlify" the tone and a desire to not make it sound like the formal documentation. Among other ways in which we approached this issue was to start using contractions.
The question is whether this actually is a problem for people, as seems to be the received wisdom. Keith Ward, who's the Editor-in-Chief of MSDN Magazine, wondered the same thing. In a blog post not long ago, he posed this question:I was told by an author that using contractions in MSDN Magazine can cause confusion in readers for whom English is not their native tongue. I haven’t heard this as a general complaint, and wanted to find out if that is indeed the case.
Can those of you who have an opinion on this please weigh in? Apparently he got a lot of responses, some of which were left as comments on the blog entry. He followed up with another blog post, in which he noted that a big majority of people reported that it wasn't a problem for them to read English that contains contractions. (Of the people who left comments, many specifically noted that they are non-native speakers.)
There were some opinions about the tone that contractions convey ("are not appropriate for formal content"). Keith responded to this explicitly by saying:I'm not a big fan of the formal tone that doesn't allow contractions, and although MSDN is a serious magazine, that doesn't mean the style has to be uber-stiff. We haven't surveyed the readers of our new, friendlified documentation about this issue in particular. Among the inside stakeholders in the docs (that is, folks inside the company who have a say about the documentation), the contractions are a big go.
The problem is, we're not really used to writing that way. So one of the things I now do as part of the editing cycle is to do a "contractions pass" to convert appropriate phrases into contractions. The first step was to identify all the contractions in English, which turns out to be quite a few. We don't need nearly all of them (for example, the incidence of the phrase she will is pretty low in our docs). I end up looking for these:
- are not
- cannot
- could not
- did not
- do not
- does not
- has not
- had not
- have not
- is not
- it is
- should not
- that is (Not as "that is, ...")
| - there is
- they will
- they would
- was not
- were not
- will not
- would not
- you are
- you have (as auxiliary only)
- you will
- you would
- what is
|
(I have a more comprehensive list up as a text file that you can look at, but I don't promise completeness.)
I'm not mechanical about these substitutions. I would never dream of doing a global search-and-replace for these. I examine every phrase that might potentially be replaced with a contraction and consider not just whether it's a valid substitution but whether the result would sound awkward or would change the intended meaning. (As an example of this last, a writer might have Be sure that you do not delete this file, in which "do not" conveys a certain vehemence that might be lost if replaced with don't.)
I guess I would like to hear from our readers about this effort at contractions. For the time being, we're assuming it's a good thing.
Here are a few resources on this topic:
|
|
