Comments to the questionnaire in Tip of the month February 1999

All comments are shown as received. Some respondents send two comments. They are merged into one, or (if obvious) the last and most complete answer is shown. Two comments were send as separate mails without answering the questionnaire. Personal comments to me has been removed. Identification items are made neutral and the changed text is shown in [ ].

Data processing of the questionnaires: the answers were received using Pegasus Mail 3.01d. The content of the Pegasus folder was then converted to an MS Excel 97 file by means of Pm2db, which I wrote myself in MS Visual Basic 6 Pro.


Back to the main tip for February 1999.

Comments


Trained "linguists" normally distinguish between prescriptive and descriptive grammars, and between grammar and punctuation (your first example is punctuation, not grammar).

The only grammatical rules that are hard and fast are those that are based on simple logic. For example, dangling modifiers make sentences ambiguous. It's far more important to be able to see and correct that ambiguity than to memorize a series of overly simplistic 'grammatical' rules. True grammar is a living thing, and is horribly complex and inscrutable. Grade-school is a deceptively simple and often incorrect interpretation of living language. While some of the 'rules' we are taught have some value in the real world, they are not by any means the whole story.

While I don't think that all professional writers have to be trained linguists, I do believe that effective writers have a solid grasp of the logical rules of language and are able to distinguish them from the illogical rules.


I'm a Canadian working for an American company here in [European Country]. I'm supposed to be writing in American style English but find that difficult. Although I can write with American spellings (color vs. colour), I cannot write with American grammar and punctuation. When I see American grammer and punctuation, it just strikes me as wrong. But then some British English strikes me as wrong as well (a company name being plural as opposed to single).

I don't think most readers of tech docs want to see a "How to read this manual" comment. I'm not writing for English grads, I'm writing for software users. I don't break many rules, but I definitely use the British style of placing periods inside the quote only if the quote itself is a sentence. Same for parentheses. I don't care what the rules are, it's stupid!

In college, I once got a full letter grade demotion on a paper for placing a period outside of the parentheses. Example: Type a name for this input (up to 5 characters). The professor and I argued and he won (of course) saying it should read "Type a name for this input (up to 5 characters.)

AAUGH. Does that make any sense at all?

I love that you wrote this because I see so much bunk about "proper" grammar. The ultimate goal of any tech doc is usability. Period. If the "proper" grammar interferes with that, usability reigns. IMHO.


I like your idea of "How to read this manual" to explain why you broke the rules. Also, I'm part of the group that sees grammar as an observation of what we do, not a rule book we must abide by. When enough of us do something differently, the "rule" will change to reflect that.

Giving an explanation, as you suggest, for variances from the current set of grammatical "rules" does several things:
- Alerts your readers to your variant usage and provides the reasoning behind it
- Makes you think about exactly why you are varying from the grammatical norm, and helps you clarify your position
- Provides the grammarians with documentation for future changes to the "rules"


In German, there is a rule to write out numbers < 12 with letters. But in technical documentation I prefer to write any number as a figure.
First reason: All numbers appear equally written.
Second reason: When you read "ein" in German, this can mean the number "one" or the indefinite article "a/an".
Third reason: Often, the figures in the text refer to e.g. an inscription on an instrument.
When I write German manuals, I try to write short sentences. If that is not possible sometimes, I have to change the syntax to make it easier to understand.

In the example about three or 3, clearly you would write "3" because the keyboard does not show "three."

I think that the English language is rich enough to allow us to express ourselves without seriously bending the rules of grammar or getting sloppy". However, some of the stern rules that were mentioned as examples, I would probably break from time to time, as they seem antiquated and inapropriate.

I think that users will accept grammatical "errors" in technical documentation without the need to provide excuses when the error make the explanation clearer.

I think that what you present as grammatical rules are not so much grammatical rules as stylistic conventions. I might break some of them, but I would not break grammatical rules.

People are constantly changing the rules, even if these are not recognised officially. Thirty years ago, the BBC would always say, "None of the people was...". Now, I notice, they say, "None of the people were...".
I don't think your example 3 is good: if a "3" is written on the button, everyone would write "press 3".

This applies especially to localisation and topic issues, and of course, is audience specific. But in general, we are here to make ourselves clear, not to promote usage of correct grammar

Technical writers have to understand that their only purpose is to make the user understand. Nobody (except the terminally sad) reads technical manuals from cover to cover and nobody cares about things like written numerals, apart from other technical writers.

I am a Japanese and I tranlate Japanese technical documents into English. I think this issue is very interesting not only because it relates to the evolution of a language, but also it involves cultural issues since in this globalized age, technical documents written in English are read and written by so many non-English-speaking people (like me).

When I read the tip of this month, I realized how prejuduced I was about English, which I mean I used to believe that American English is the world standard, especially in the international marketplace. (maybe most Japanese think like me.)

When I create user manuals in English, I often follow Microsofts' manuals as an example.

I blindly believe that such American user manuals are best examples to follow, and that nonnative spekers of English who writes technical documents in English will think like me.

Some peculiar grammatical rules of American English is also authoritative!!

So, if I ever read a manual where numbers below 10 are not spelled out, I will think, "This manual mey be written by non-English-speaking people. Maybe there are many strange English included.

Let's not read it seriously." Maybe your point of view is not so prejudiced.

Bad grammer is bad grammer. We Japanese are not brave enough to complain about bad English grammer.

But even after I realized how prejudiced I am, I still want to cling to the currently accepted standard English. Language is a living creature. It will evolve as time goes by and people change. Even though there is a good idea to modify the current grammer, if the new rule is applied too earlier, long before most people accept it as a best option, it only gives a document uneducated and unauthoritative image. In any time, authoritative documents use rather obsolete dated-sounding wording.

Thank you for reading my disorganized and unclear composition!


The language that best communicates is the language your readers best understand, period.  It isn't always English, the Queen's English, American.  If audience has heavy use of colloquialisms,  slang, special use of technical terms, etc. I take that into account when communicating to them in writing, and sometimes that means proper grammar rules are dispensed in favor of more effective means to relate to the audience.

As a user all I ask really is that the author/editor be consistent.  If you're going to use "because" rather than "since" (or vice versa) unless a specific time is clearly invoked or insist on using "Although" at the beginning of sentences and "though" internally, do so all the time.

I was educated in American schools and was taught the "British" style of punctuation in Example 1.  While it does not bother me to see the punctuation inside the quotes, I do notice.

Do you realize that you used the word "extend" instead of "extent" in this article?  I understood what you meant, but it caused a break in my reading.  One of your previous tips recommended that manuals be edited by a native speaker.  I couldn't agree more.  This is not a criticism; my hat's off to you and others who write and speak several languages.  I've recently seen some travel brochures from Germany that would have been a lot more effective had they been edited by a native English speaker, a recommendation from you in a previous tip of the month.


My goal is clarity, which trumps perfect grammar once in a while.  However, if I choose to break a rule, I break the same rule everywhere in the manual to preserve consistency.

It may be the American rule to always place commas outside of quotes, but many more writers here are following the British style.  I know I do, but not because it was rule in one place or another, it just makes sense!

It all depends on the rule broken.

I am finally beginning to accept the structure everybody <singular> ... their <plural>" -- which is SPOKEN by everybody and increasingly finding its way into print. As a matter of fact it's in today's WSJ management section: "everyone has to make their own decision..."


As a medical writer, international lecturer, patient adherence educator, physician-patient facilitator of communication, and seminar leader of better medical writing for pharmaceutical executives, HMO leaders, and physicians, I think that we have a responsibility to make our readers and listeners appreciate correct English, to read and hear correct English as the ONLY "user-friendly" (not one of my favorite phrases) form of speech.

I grew up in the U.S., but am writing in Canada, which sometimes follow U.S. and sometimes British rules on spelling (and am not sure about grammar, never having realized the difference until you mentioned it). I follow British rules on punctuation within quotes and usually use digits for numbers. I think that your how to read" example was quite awkward. I would not bother mentioning that we know the rules of grammar (that can be assumed) but would consider including, along with other conventions listed (such as what bold, special fonts, etc. indicate) consistent exceptions (e.g.: in an effort to make this document easier to read, digits are used for numbers and punctuation occurs outside of quotation marks.

Strict adherence to grammar often is user friendly. However, one should never be so dogmatic as to sacrifice readability for principle.

I always err on the side of reference sources since many of our users are technical people who would not be agreeable to having broken grammatical rules.


I HATE pedantry for the sake of pedantry and agree that the "ungrammatical" solutions you have given in the Tip of the Month are more user-friendly. CLARITY IS KING whether grammatically correct or not. Unfortunately, few writers have a firm enough grasp on grammar to know how and when to break the rules, or why!

In some cases the punctuation depends on house style - "The Observer", a heavyweight Sunday newspaper here in the UK places the full stop according to US convention.
I frequently omit full stops when describing HTML tags etc. because of the potential for confusion. My rationale is that readers aren't likely to notice a missing full stop but might get confused with it there.

I think it depends a lot on what you consider hard-and-fast "rules" and how familiar you are with the conventions of English. If you understand exactly what you are doing, and it does not interfere with readability, then it often makes sense to "break" those rules for increased readability.

However, I am not sure I agree with the specific examples the author used. First of all, I prefer to change the font to indicate something a reader must type exactly, rather than put it into quotes at all, which eliminates the question of whether the punctuation goes inside or outside.

I don't think using inconsistent syntax in parallel constructions, for example, ever enhances readability. But judicious use of "split" infinitives or ending a sentence with a preposition (or particle that has the same form)is seldom a problem.

I think the most important thing is clear writing, though that may encompass different ideas for different writers. I believe that if it is logical to break a "rule" to make a document or procedure clearer, it is not necessary to make this explicit to readers as a "broken rule." If there is a "Conventions" section, it may make sense to mention some changes, if they are used in a particular way in the document.


Most users don't know the grammatical rules (they're awfully confusing sometimes). They only know when you've broken the ones they use all the time in their speech. Rules like the punctuation example you've given aren't really grammar rules, anyway. They are style issues. So, I would break rules any day to provide clarity for the reader. I would only inform them of doing so if it was also necessary for clarity.

As long as your writing and spellings are consistant and do in fact make the document easier for the reader to follow, I think breaking a rule is fine.

The US rules on quotes and punctuation is particularly relevant to me as a software writer.  I now use the British method for all my writing, because it's more logical.  An exception would be a submission to a highly structured journal.

Another rule I regularly break, and this is controversial, is the subject/verb agreement when trying to avoid gender issues.  For example:  The email recipient will recieve an error if they try to open the message without..."  Use of "they" eliminates a repetitive "he/she" or trying to use an equal amount of she's and he's, both of which I feel are highly distracting.

A rule that many people ignore, but I follow, is restrictive clauses--which versus that.  Many people use "which" for both restrictive and non-restrictive and have varying stances on comma usage in this situation.  I believe that "which" and "that" provide valuable clues to the reader and can change meaning drastically.

I do not include a reference to grammatical issues in a "How to" section. In my opinion, this section is not meant to justify my choices but to tell users about devices the book uses to make their learning process more efficient--for example: icons for tips and cautions that make them easily identifiable; bold type that makes menu names and commands stand out when they're scanning a page of instructions.  My justification for grammar usage comes in consistency--if someone notices a grammar error and is annoyed by it, odds are my mentioning it in an intro section is not going to mollify them, even if they do discover it.


I would rewrite or avoid the situation that "necessitates" breaking a grammar rule.
...
I know it takes more time to blend user friendliness and technical accuracy, but my opinion is that there is always another way to present the information.

I do admit to breaking grammatical rules, but not for the sake of user friendliness: only when I don't have time to figure out a better way! ;->


I think you beg the question by setting up a dichotomy between correct grammar and user-friendly writing. If communicating with the audience/reader is uppermost in the writer's mind, the distinction you have made disappears.

For example, if you are writing for a British audience, the British style of punctuating quotations is correct (though I would not call this issue grammatical) whereas that style would be incorrect for a U. S. audience--and vice versa.
To give a related example, philosophers in the U. S. writing for other philosophers use single rather than double quotation marks where nonphilosophers would use double ones. Single quotation marks are simply a convention in philosophical writing. No one should call them incorrect when they are used in that context. They would, however, be incorrect in some contexts.

Grammatical and mechanical issues in writing are, at last, rhetorical. Whatever distracts the reader from the writer's purpose is incorrect.


I would accept another author breaking the rules only if that rule was broken consistently and was obviously broken for a reason. If that reason is not obvious, then I would appreciate a note in the How to read section.

By the way, I assumed that for Education, Technical meant Technical Writing. If it does not, I'm Other.


None of the examples provided were 'grammatical' in my opinion: more like style, punctuation or preferred usage. Actual syntactic rules exist for clarity. Where common usage far outweighed academic prescriptive rules I'd go for clarity.

Your reference to numerical style isn't syntactic. If you're talking about Page 9 it makes sense to use a numeral. If you're talking about nine pages it looks awful. Sometimes it's ambiguous, too.