Re: correct English usage (for every occasion?)
On 05/04/12 06:07, Dotan Cohen wrote:
> On Wed, Apr 4, 2012 at 10:21, Lisi <lisi.reisz@gmail.com> wrote:
>> On Wednesday 04 April 2012 14:41:48 you wrote:
>>> Colloquial English is liberal to change,
Yes. I understand what you mean. And that's a classic example of
something written by some for whom English is not their first language.
I asked natives with different literacy levels what they thought of that
statement. I've only reproduced the more entertaining ones for this
colloquial discussion, the last two would be the audience for a FAQ.
"Huh?" [too embarrassed to admit not knowing what colloquial means,
possibly suspects the Liberal party is involved] left school at 14 and
attended the University of Life, doesn't/can't read, eats at
"restaurants" that have pictures on the menu.
"Derr, and water is wet." [if colloquial didn't change according to local
custom, it wouldn't be colloquial, and, "sounds like someone ate the
dictionary", thought the statement was "pretentious".] Undergraduate
arts degree, reads only when necessary, preferably "graphic novels".
"W*nker" (colloquialism for "you're not from around here are you?" + and
element of "derrr") [not a fan of Australia's immigration policy ie.
picked the statement as made by a non-native] Masters degree in Science,
multi language skills, reads a lot.
So two comprehended the statement correctly. But both added meaning you
didn't intend.
Tricky stuff indeed, and that should not be read to imply your English
is not good (above average).
>>> but software manuals should not be written in colloquial
>>> English.
>>>
Generally, yes. The intention and audience is the determining factor.
Sometimes the line between advertising and instruction is blurred, the
targeted audience may have a problem with vowels.
My general rule is to write first for the lowest common denominator. So
the first things found should be the simplest - either drill down to
footnotes or appendixes for more detail. Psychology is a large part of
both getting people to read, and getting to understand what you say.
Of course everyone knows this, which is why we are all master
communicators, and Steven King ekes out a living hauling garbage. :-)
>>> There is a more professional language that should be used in
>>> manuals.
Again, generally, yes. A manual implies reading. To be able to read
requires a level of literacy that not everyone possesses. Therefore a
manual that is useful requires a level of literacy lower than that of
the intended audience.
The very successful "Dummies Guide to" range of books recognises this.
Know you audience, then split-test. Sorry, I've no recommendations on
how to do this in the instance being discussed.
<snipped>
> I just bothered to look up the names of English writing styles.
There's a dangerous precedent ;-p
<snipped>
> There exists a writing style called "technical" and if a manual
> writer cannot manage that, then he should err on the side of formal,
> not casual, in my opinion.
It's a FAQ, not a "manual". A FAQ "style" is point form distillations of
complex threads and multiple posts. Jargon, a feature of technical
documentation should be avoided in all types of quick access
documentation. A FAQ is a form of "quick access"[*1] documentation.
My opinion and experience, as a documentation writer, is that "technical
writing" is used for "technical documentation".
In this instance we're talking about a FAQ - for which the preferred
style is "plain english[*2]" written at an appropriate level[*3].
Some colloquialisms are acceptable in plain english. Subject to the
general rule that any document should speak in a voice best heard by the
audience. ie. I wouldn't generally write "would not" in a software FAQ,
but I would use it in a "user guide".
Dear Dotan, there is a "Formal" style of "business" communication, as I
hope "you and I" can agree. It is generally referred to as "formal
business" style. When used inappropriately it's referred to as a
"stilted" style. :-)
"Casual" style sounds like a dress code, I've never seen the term used
in documentation specifications. I suspect you looked up "Aunt Betty's
guide to letter writing for young adults" :-D
Advertising copywriters and journalists will have different writing
"styles" again.
[*1]I just made that term up.
[*2]AKA clear english.
[*3]see Flesch, Gunning, Kincaid and others.
> That said, many FOSS manuals and UI elements are written in the
> casual or even in street vernacular.
Many Software manuals and UI elements are written by amateurs and
illiterates ;-p So I'm not sure what your point is there.
The determining factors should be:-
;whether it's easily readable (or it won't get read)
;whether the documentation accurately conveys the correct meaning to the
reader (or reading, and writing it, is a waste of time).
"Convention" and "popular opinion" are irrelevant unless they conform
with those factors.
Amongst the many "good/proper writing" factors *not* discussed so far is
context. ie.the style should be consistent throughout the document.
Voice, tone, and syntax are elements of the compositional style, but
layout style (lots of white space, short paragraphs) also plays a large
part in accessibility and allowing comprehension.
Both styles determine whether a document will read "easily", but a
really only the "colouring in" part of writing.
Words are such loose fences around concepts that semiotics and NLP play
a large part in determining comprehension - that's the "painting" side
of writing.
NOTE: a good, highly experienced, documentation writer can consistently
produce 200 words a day. I'm not that good, and I can't spend all day on
this post (so don't expect proof reading).
<snipped>
Kind regards
--
Iceweasel/Firefox/Chrome/Chromium/Iceape/IE extensions for finding
answers to questions about Debian:-
https://addons.mozilla.org/en-US/firefox/collections/Scott_Ferguson/debian/
Reply to: