(1) Thanks, John. The translator section will definitely be useful.
(2) Attached, find a diff with some spelling mistakes.
(3) I propose changing
\subsection{The First Is In Charge}
to:
\subsection{Who's the Chief?}
and adding a sentence at the end of the first paragraph, so that it becomes:
If you were the first person to start translating the manuals, you're the
LyXDoc Translation Project Chief for your language. If you are the only
person translating the LyXDocs, that automatically makes you the Translation
Project Chief. You can also become Chief if the current Chief gives control
to you, or if you take over when the current Chief disappears.
(3a) we could also mention that the translation chief is mentioned on the
devel.lyx.org translation page.
-----------------------------------------------------------------
(4) It's too darned long! I think it's very important to have translation
instructions, and I think it's very good to have explicit style instructions
so that the manuals look the same. However, IMO, we don't need that many
instructions.
Some wc output:
Before 3/21: 1689 4419 29970
3/22: 2459 6410 44060
today: 4841 13734 94749
Does DocStyle need to be 3/4 the size of the tutorial? (And there are still
some "more to come..." comments in DocStyle.) John, I fear that in your
drive to give explicit instructions, you've broken one of your own rules;
you're dumbing down.
(4a) stuff that doesn't need to be in there
Your story about germany is interesting and makes a point, but I don't think
you need to make it. Translators already know (at least) two languages, so
they know that not everything translates. If they don't, a one-sentence
"things like slang and humor don't always translate" would work, too.
Other places have discussion which is interesting, but which I think just
have to be cut for space considerations. For example, I would take section
9.2, which is four pages, and shorten it considerably. At the least make the
subsections into subsection*'s. But I think I would make them an enumerate.
Most of them don't need supporting paragraphs. 9.3.1 is titled
"Write as if you are explaining LyX to a colleague you know well." Do you
really need an enumerate with three points, one of which is "Use a
conversational style in your writing. Pretend you are teaching LyX to a
colleague you know well."?
One way to shorten this considerably would be to construct the translator
section as a "diff" to the english-only section. Section 9.3.1 could just
say "Use a style that is polite without being too formal. If, in your
culture, informal language is appropriate to use with a colleague, use
informal speech in the translation of the manual."
(4b) too much detail
Once the translators know that slang & idioms don't translate, how much
detail do you need to give about not translating slang & idioms? How about
"feel free to remove slang if it doesn't translate well; feel free to insert
your own if and when it's appropriate. Same goes for idioms and humor.
Always keep in mind the main goal of the docs: thorough and accurate
descriptions of how to use LyX, in the style you would use to talk to a
colleague you know well."
Here's the Addendum title description:
-----------
The title of the Addendum:
The title will use the "Title" paragraph environment.
The title will be written in your native language.
In your native tongue, the title will read:
Documentation Project Style Sheet:
Addendum for the <foo> Translation Project
(Replace "<foo>" with the name of your language.)
If your language is a European language that borrows from Latin, you
shouldn't need to translate the word "Addendum."
If your language has no ties to Latin (e.g. : Japanese, possibly Russian), or
"Addendum" translates into your langauge as appendix, do the following:
Replace "Addendum" with the translation into your native language of the word
"Supplement." If "Supplement" also fails to translate well, try
"Additions." Whatever you choose to replace "Addendum,"
it must not have the same translation as the word appendix.
-----------
I don't know about you, John, but I think I'd be offended to be dumbed down
like this. Yes, standards require a bit more detail, but come on. How about
"For your title, appropriately translate 'Documentation Project Style Sheet:
Addendum for the <foo> Translation Project' (Replace <foo> with the name of
your language."
If you really want to, add "Try to translate 'addendum' to mean 'supplement'
or 'addition', not 'appendix'."
The current addendum title item takes up half a page!
(4c) too much repetition
I know you're a big believer in repeating things for emphasis. However, I
counted five different copies of "When in doubt, compromise. When in doubt,
use good judgement."
-----------------------------------------------------------------
I know it's kind of amusing that I---who am known for long e-mails above
all---am complaining that DocStyle is too long. In a really long e-mail, no
less! But it is. You tell documenters to read DocStyle and then read it
again. Very good advice, but noone will do it for a 35+ page document! The
12 pages that were there originally were very useful when I was writing the
tutorial, but I think DocStyle needs to have an upper limit of maybe 20
pages, if you really want people to read the whole thing (more than once!)
If we want to reach 20 pages, I think we would need to pare the
non-translation part, too, by a bit. 2.5 pages on author's notes and
footnotes?
While the conversational aspect of the docs is one of their best features,
we can't allow conversational details to bloat the docs.
I hope you don't take this as an attack on the docs. As I mentioned, I read
DocStyle a few times, and referenced it many more times. But people are
lazy. They won't read a 35 page style document, and therefore they won't
remember where to find what font to write HFill in, and the docs won't be
any better.
-Amir
--- DocStyle.lyx Tue Apr 20 09:49:58 1999
+++ a.lyx Tue Apr 20 11:58:58 1999
@@ -1,4 +1,4 @@
-#This file was created by <candide> Sun Apr 18 21:25:04 1999
+#This file was created by <karger> Tue Apr 20 11:58:57 1999
#LyX 1.0 (C) 1995-1999 Matthias Ettrich and the LyX Team
\lyxformat 2.15
\textclass article
@@ -1027,8 +1027,8 @@
\begin_deeper
\layout Standard
-If you really, really need to name a widget, the popup its on, and the menu
- item used to open the popup, then write it out:
+If you really, really need to name a widget, the popup it's on, and the
+ menu item used to open the popup, then write it out:
\begin_inset Quotes eld
\end_inset
@@ -1419,7 +1419,7 @@
\begin_inset Quotes erd
\end_inset
- and any description of the 3 mice buttons have no special handling.
+ and any description of the 3 mouse buttons have no special handling.
Don't typeset them in any other font than the default, which is Roman.
Exception: you're writing an Author's Note (see section
\begin_inset LatexCommand \ref{sec:author-notes}
@@ -1777,7 +1777,7 @@
documentation, I exclude the translations.
Right now, we don't have enough people to cover the manuals in one language,
let alone more than one.
- Subsequently, the tranlsations tend to be just that --- translations of
+ Subsequently, the translations tend to be just that --- translations of
the English version of the LyX manuals.
The translation efforts require have their own set of guidelines.
See section
@@ -1871,7 +1871,7 @@
\end_deeper
\layout Standard
-Note that we have simce replaced the
+Note that we have since replaced the
\begin_inset Quotes eld
\end_inset
@@ -2165,7 +2165,7 @@
\begin_inset Quotes erd
\end_inset
- are or any other variant are forbidden.
+ or any other variant are forbidden.
The Author's Note must end with an
\family typewriter
em
@@ -2259,7 +2259,7 @@
descriptions, please use them properly.
I have listed some additional restrictions above.
Some of you may balk at these restrictions.
- Nevertheless, there is a reason for them: if you have an overwhemling desire
+ Nevertheless, there is a reason for them: if you have an overwhelming desire
to mix or modify footnotes, Personal Notes, and Author's Notes, you shouldn't
be using any of them.
More specifically, you're trying to use a hammer to drive in a screw.
@@ -2916,7 +2916,7 @@
\layout Standard
In general, stick to short sentences in written English.
- Getting rid of passive void (
+ Getting rid of passive voice (
\begin_inset Quotes eld
\end_inset
@@ -3135,9 +3135,9 @@
and waits for the professor to respond.
For the students to talk to one another during the lecture, even to ask
- one another a question, is considerer rude.
- Germans students, however, regularly whisper to each other, discussing
- the lecture or asking each other questions while the professor is speaking.
+ one another a question, is considered rude.
+ German students, however, regularly whisper to each other, discussing the
+ lecture or asking each other questions while the professor is speaking.
As long as this side-dialogue between students does not disturb anyone
or dominate the entirety of the class, no one thinks anything of it.
\layout Standard
@@ -3186,7 +3186,7 @@
smiled a relieved smile.
He had been spending the entire semester cracking jokes (a fact we realized
later) to these seemingly humorless Americans who did nothing but sit there
- and diligently transscribe his every word.
+ and diligently transcribe his every word.
He had been using all of the verbal cues that say,
\begin_inset Quotes eld
\end_inset
@@ -3242,7 +3242,7 @@
\emph default
boring.
They would engaged the reader, as if in friendly conversation.
- I realize now, however, that the LyX Documentation engage the reader as
+ I realize now, however, that the LyX Documentation engages the reader as
if it were a friendly conversation held in America.
Or Australia.
Or Canada.
@@ -3449,9 +3449,9 @@
\end_float
\layout Standard
-No, I don't care what you're English teacher or professor told you; the
- prepositions in your native tongue have no direct translation into English,
- and vice versa.
+No, I don't care what your English teacher or professor told you; the prepositio
+ns in your native tongue have no direct translation into English, and vice
+ versa.
Let's look at an example:
\begin_inset Quotes eld
\end_inset
@@ -3741,7 +3741,7 @@
in the sense that they are seldom used by normal people in everyday speech.
\layout Standard
-We who write the LyX manuals, original or translated, see to
+We who write the LyX manuals, original or translated, seek to
\emph on
inform
\emph default
@@ -4245,7 +4245,7 @@
\begin_inset Quotes eld
\end_inset
-Adddendum.
+Addendum.
\begin_inset Quotes erd
\end_inset
@@ -4262,7 +4262,7 @@
\begin_inset Quotes erd
\end_inset
- translates into your langauge as
+ translates into your language as
\begin_inset Quotes eld
\end_inset
@@ -4731,7 +4731,7 @@
\newline
or
\newline
-What to do when a fond doesn't exist:
+What to do when a font doesn't exist:
\begin_deeper
\layout List
\labelwidthstring MMMMMMMM
