slightly long and detailed proposal for documentation-translation workflow

[Ed Trager]

Hi, Michael,

Just a few comments for consideration by everyone:

> ...
> Doc writing conventions:
>
> Some linguistic research has been done on "simplified English" as a
> subset of English to use for low-level learners, and I think that it
> might be a good place to look for ways to simplify the source_docs.
> But just thinking intuitively, I have cooked up the following
> suggestions in order to generate discussion:
>
>     * Pronouns.
>           o Use the first-person singular pronoun "I" to represent the
> author of the docs,
>           o the second-person singular pronoun "you" to represent the
> reader of the docs, and
>           o the first-person plural pronoun "we" to represent the OLPC project.
>
>           o Examples. "We have designed a screen that switches to
> black-and-white to conserve energy. I will explain how to switch your
> screen to black-and-white. First, you press the X button on your
> keyboard...." Because we want the docs to be easily translated and
> easily understood, the tone should be personal, using "I" for the
> voice of the writer. This will be easier for amateur translators to
> translate and easier for younger readers to understand. This will also
> help the writer avoid the passive construction, which is very
> difficult for some non-native English speakers to understand.

I agree completely that the English passive construction should be
avoided at all times.

I mostly agree with your suggestion on use of pronouns.  Use of "I"
and "we" are fine.

REGARDING THE PRONOUN "YOU" IN ENGLISH:
----------------------------------------------------------

However, as a native English speaker, I find the use of the pronoun
"you" in the imperative mood often quite jarring.

Imperative sentences in which the "you" is absent are understood by
native speakers of English to convey a softer, less imperative tone.
Such sentences are considered more polite. Compare:

(A) "First you press the X button on the keyboard."

 ... versus:

(B) "First, press the X button on the keyboard."

One or two instances of "you" in imperatives or directions in spoken
or written English may not seem too bad, but after a series of them,
it becomes irritating.

So while I have no objection to simple English which will be easily
understood by younger learners of the language, we must also be sure
that we do not proscribe an incorrect idea regarding the usage of the
pronoun "you" in imperative sentences in English.

In short, it is *not* OK to use "you" repeatedly in a series of
imperatives or directions (such as instructions for using a laptop).
The absence of the pronoun "you" is preferred when giving directions
in English.

REGARDING POSSESSIVE PRONOUNS:
-----------------------------------------------

Look again at the sentances Michael used for his example:

> I will explain how to switch your screen to black-and-white.
> First, you press the X button on your keyboard...."

English speakers make frequent use of possessive pronouns, as is the
case here with : "your screen" , "your keyboard" .

But in many other languages (perhaps most other languages?) we would
not use possessive pronouns here at all.  All of these English
"your"s, if translated quite directly into foreign languages, results
in very annoying and unnatural sounding texts in my experience.

So I would advise we try to fix the English from the start by avoiding
unecessary invocations of possessive pronouns, especially "your":

      I will explain how to switch the screen to black-and-white.
      First, press the X button on the keyboard...."

I basically agree with the rest of Michael's suggestions, so that's
all the comments I have.

-- Ed Trager