Wonderful! Helping to put together volunteers; 3 technical writers have made themselves available for assisting with documentation; anyone who is interested in helping work out the "collaborative tools/localization tools" -- please touch base. They are interested in serving the OLPC project and am suggesting that strategy be developed for channeling more volunteers -- then I expect there will be more -- discussing assigning a writer to each activity if we are so lucky.

Comments: *reading level* - 100% agree on simplified technical english. great if developers/others can use simplified english in original note-taking. if you have ms word you can run a test that calculates age level - 6th grade is probably good. if you don't have ms word you can send an open office doc or wiki url where you are taking notes.

<br><br>*screenshots*<br>- visuals are important. beyond providing reference material on "how" -- helpful if developers can think of a step by step scenario that someone can walk through to "try" the activity. when writing books I found it helpful to walk through a process/task, and take screenshots, drop them into a document, then go back and write captions -- then as necessary filling in with background info

<br>- good to think of whether you can provide a concept, task or reference. all three categories are helpful<br>- suggest taking screenshots in as small a format as possible; if you take the entire screen and can crop to the relevant section, great -- otherwise in caption you could include notes to crop to a certain area

- for localization of screenshots, suggest not worrying about in-language text for now -- but that localization filenaming convention be established for naming screenshots. immediate term: blah-en or blah-sp. not clear on if OLPC has decided on ISO language codes.

<br><br>*tools*<br>- have been working on looking at various tools for documentation/localization; if interested/working on such things, please get in touch. I will subscribe to <a href="mailto:localization@lists.laptop.org">

localization@lists.laptop.org</a> (btw Idiom has donated an instance of idiom worldserver that can be studied as a method of incubating open source alternative, trying to find configuration help.)<br><br>*portal*<br>- started google group recently as repository for documentation strategy, files and information, and as temporary method of corralling/versioning content, and for having an email list. could be precursor to 

<a href="mailto:doc@lists.laptop.org">doc@lists.laptop.org</a> -- if interested, touch base.<br><br>*localization*<br>Lingo Systems stepped up to the plate with build 542 notes and helping to get translated into 7 different languages; not sure about this time around. probably most scalable approach will be to do things in stages, using a "human content management system" until more automation can occur. Suggesting 3 stages - alpha - beta (draft) - publis

<br><br>> alpha: have a dynamic wiki-based alpha TOC, from which a "TOC code freeze" can be made by tech writers working back from translation deadline, pulling TOC into editing, then pulling content in from the live wiki pages where notes are and editing

> beta:  dropping TOC and pages into beta wiki pages and pursuing 3 channel localization strategy (until something better can be found) -- channel 1: translation can occur directly within wiki page (not ideal, no translation memory, can be time consuming and prone to human error) or copy and pasted into word along with note that it is being translated - channel 2: as content is dropped into beta wiki page, it is also placed on wordpress - advantage here is simply that we can connect to world wide lexicon which has a distributed translation roundtrip solution -- channel 3: putting content into word processing documents and circulating to professional translators if/as available, who often prefer RTF format.

> publishing: based on what translations are available, printing out chapters/modules from TOC code freeze out to PDF and HTML. Practical world -- for upcoming release -- my understanding is we have a little under two weeks, and that the "translation freeze" should be by midnight this friday EST -- this would be for any documentation that is being handled already -- we've already been working on aggegrating notes, links to existing wiki pages, and massaging previous notes. so the goal at the moment for this release is simply to get something better and more cohesive than build 542 notes -- problem is translation. not sure if lingo will come through, at this point need volunteers; ideally professional bilingual technical writers but any translation will help. it's wasteful not to have all of this in a cms so we could just send the "new" material for translation but it would be too time consuming to go through and calculate localization based on x-diffs from wiki pages (unless someone knows of an existing, working, wiki-based translation management plug-in), so we restarted documentation from scratch.

<br><br>so the following languages are needed -- if anyone knows anyone who speaks english and any of the languages below other than english:<br><br>1st priority: es, pt, en, hi, am<br>

es = spanish | pt = portuguese | en = english | hi = hindi | am = amharic (ethiopia)<br><br>2nd: ar, th, he, fr , ru<br>ar = arabic | th = thai  | he = <span id="st" name="st" class="st">Hebrew</span> | Fr = French  ru = russian

<br>

<br><br><br><div><span class="gmail_quote">On 10/15/07, <b class="gmail_sendername">Micheal Cooper</b> <<a href="mailto:cooper.me@gmail.com">cooper.me@gmail.com</a>> wrote:</span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">

I sent these ideas to Jim Gettys, who suggested that I send them to<br>the development and localization mailing lists.<br><br>------<br>Summary:<br><br>    * Write/ Edit primary documentation according to an explicit set<br>

of writing conventions designed to minimize ambiguity and complexity in order to facilitate translation.     * Treat this English documentation as source code which is meant to be translated/compiled into user languages.

<br>    * Use/Create collaboration tools to make translation,<br>distribution, and maintenance of docs more efficient.<br><br><br>------<br>Assumptions:<br><br>Some of those doing translation will not be professional translators

<br>fully bilingual in English and the target language. They might be any<br>of the following:<br><br>    * a village teacher who speaks the target language as her first<br>language (L1) and English as a weak second language (L2);

<br>    * a missionary who speaks English as L1 or L2 (in the case of a<br>French missionary in Africa, for example) and the target language as a<br>weak L3;<br>    * a professional translator who speaks a non-English L1, reads and

<br>writes the target language as L2, and knows English as just a subject<br>that he or she studied in school and uses for travel;<br>    * a native L1 speaker of the target language who has immigrated to<br>a foreign country in which English is spoken as a primary or secondary

<br>language.<br><br>Many of the translators are not going to be career translators, so<br>rather than having the translator accommodate the source text, the<br>source text should accommodate the translator.<br><br>Documentation translation is particularly difficult because of how

<br>documentation is usually created. Often docs are written grudgingly at<br>the end of the project, and docs are rarely written to a uniform<br>format or set of conventions. There is little reflection on what kind<br>of docs are needed, and docs are usually not edited before they are

<br>sent off for transl and publishing. The conventional approach to<br>translation is that, when a novel or academic article is translated,<br>it is the burden of the translator to accommodate the original, and if<br>the original is unclear, this lack of clarity is translated into the

<br>target texts because the target text must be a mirror of the original.<br>I know this from direct experience, having been the translator for<br>many doc jobs from Japanese companies. The originals are often<br>incomprehensible because of ambiguity and inconsistency, as in the

<br>following examples:<br><br>    * different sections of the docs are written by different people<br>using different terminology for the same processes and entities;<br>    * unconfident writers are too brief, assuming background info and

<br>context to which the translator does not have access;<br>    * more confident writers use too many idioms and colorful<br>expressions, rambling on and on in extended and poorly-organized<br>complex sentences;<br>    * section divisions and overall organization are inconsistent,

<br>forcing the translator to restructure the original before beginning<br>the translation;<br>    * ambiguities inherent in the language itself (like the absence of<br>gendered pronouns and explicit sentence subjects in Japanese) also

<br>complicate the translation, forcing the translator to contact the<br>writer of the original, thus slowing the process and degrading<br>translator motivation and confidence.<br><br><br>Ambiguity is the biggest obstacle to translation. If it is a rush job

<br>(and it always is), and especially if the translation is being handled<br>by a middleman like a publisher or web design firm (and these days it<br>almost always is), the translator usually retreats to literal<br>translation in the face of ambiguity because there is no way to

<br>contact the author (middlemen don't want the translator to know how<br>much the client is being billed for translation) or no time to wait<br>for the reply. When the text is unclear, the translator has no choice<br>

but to translate the ambiguity itself. In the case of OLPC<br>documentation, ambiguity should be avoided at all costs. Anything that<br>interferes with teachers and students using the notebooks should be<br>avoided, and bad docs would certainly be frustrating and demotivating

<br>for the educators and pupils. In order to have translations that are<br>as clear as possible, we must have source-docs that are as clear as<br>possible.<br><br>------<br>Reconception of documentation/ translation as parallel to computer programming:

<br><br>The OLPC team uses English as a common working language, but the users<br>will be using translations, so the English documentation can be seen<br>as not a product in and of itself but as the source for all<br>translations. The English-language "source docs" should be written to

<br>a set of conventions meant to reduce ambiguity and ensure consistency,<br>even when doing so necessitates violating conventional English writing<br>style. The set of documentation standards I am proposing is similar to

<br>the set of coding conventions a programmer follows. The "source docs"<br>(though written in English) should be seen as source code which is<br>then compiled (or translated) into the many languages needed to<br>

support the users. Likewise, the source-docs should include explicit<br>comments and extra-textual blocks to clarify ambiguity introduced by<br>the writing style or inherent in the language itself, much in the same<br>way that a good programmer includes comments in source code to

<br>compensate for the lack of explanatory devices in the code itself.<br>Looping through a multi-array doesn't tell you WHY you need to do so<br>or how it plays into the next code block, just as being told that the<br>

subject of a sentence is "Suzuki-san" does not tell you if Suzuki is a<br>"she" or a "he". Most techs have had the experience of having to<br>maintain a code base which did not include sufficient comments: while

<br>"read the friendly code" or "use the source" might be good ways to<br>learn to program, this kind of detective work is not an efficient use<br>of time and effort.<br><br>------<br>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.

<br>But just thinking intuitively, I have cooked up the following<br>suggestions in order to generate discussion:<br><br>    * Pronouns.<br>          o Use the first-person singular pronoun "I" to represent the<br>

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.

<br>          o Examples. "We have designed a screen that switches to<br>black-and-white to conserve energy. I will explain how to switch your<br>screen to black-and-white. First, you press the X button on your<br>keyboard...." Because we want the docs to be easily translated and

<br>easily understood, the tone should be personal, using "I" for the<br>voice of the writer. This will be easier for amateur translators to<br>translate and easier for younger readers to understand. This will also

<br>help the writer avoid the passive construction, which is very<br>difficult for some non-native English speakers to understand.<br>    * Lists.<br>          o Use tables to explain parallel relationships, comparisons,<br>

the composition of an entity, and categorical relationships.<br>          o Use numbered lists to explain the stages of a process, the<br>steps in a sequence, or anything that has an inherent spatial or<br>temporal order or expresses precedence. Do not use numbered lists if

<br>the numbers do not relate to some inherent property of the items. A<br>grocery list should not be numbered, unless the order in which the<br>items are purchased is important.<br>          o Use bulleted lists for lists that do not have inherent

<br>order or precedence. The grocery list would be bulleted.<br>    * All comma sequences should have a comma before the last<br>conjunction, i.e. "I like to read books, eat shrimp, and run<br>marathons," rather than, "I like to read books, eat shrimp and run

<br>marathons." It is fashionable right now to leave out the last comma,<br>but doing so puts the onus of comprehension on the reader. While this<br>is a nit-picky detail, OLPC source-docs should do as much of the work

<br>as possible so that translation and comprehension are as easy as<br>possible.<br>    * Use parentheses to include supplemental information like the<br>gender of human agents, steps in a sequence, the target of a pronoun,

<br>etc. when there is any ambiguity.<br>    * Many languages, including Japanese, represent non-native names<br>in a native writing system. In Japanese, foreign names are written in<br>a phonetic script called katakana, and my name is pronounced Kuupaa

<br>Maikeru. The result is that there is a loss of data; the orthography<br>of my name (the spelling in English) is lost to any<br>Japanese-to-English translator, as is the proper pronunciation. I<br>suggest that all source-docs have personal names written in the

<br>alphabet and followed by the pronunciation written in IPA<br>(International Phonetic Alphabet) in parentheses behind it. Then<br>translators should be told to always put the original orthography in<br>parentheses after the name that they are using, so that my name would

<br>be "<katakana>Kuupaa Maikeru</katakana> (<alpha>Micheal<br>Cooper</alpha>)" in a Japanese translation.<br>    * Insert a table that acts as a glossary of terms and their<br>definitions at the beginning of each text. These would be the key

<br>nouns and verbs used in the text, terms that need to have clear<br>meanings and consistent translations. The translators would be<br>required to keep culminative lists in OO Calc or such of these key<br>terms so that, in the case that the translator changes or a group of

<br>translators is doing the job, the key terms can be kept consistent. If<br>we know ahead of time that there will be translator teams, this could<br>be covered by a webapp or by Google spreadsheets.<br>    * Idioms and culture-specific metaphors and references should be

<br>avoided or used sparingly. Of course, terminology that originated in<br>cultural metaphor, like "kill a process" and "reboot the server" would<br>be treated as key terms and added to the glossary to be translated

<br>consistently, but more creative and expressive language ("you can type<br>like a banshee", "students will be on it like white on rice",<br>"resulting in a Mickey Mouse, vanilla solution to the problem") should

<br>be curtailed.<br>    * Use words, mathematical symbols, and visuals to reinforce and<br>enhance purely verbal explanations with conceptual representations of<br>information (I am thinking Edward Tufte here), i.e. (poor example, but

<br>here goes) "I will show you how to teach your students to create<br>multimedia presentations. <in box> Sound + Pictures = Multimedia </in<br>box>." I think you get the idea, though.<br>    * The source-docs be organized so that each section and each

<br>paragraph is identified by a number and that the translators be<br>required to maintain this organization so that paragraph 61 in the<br>Yoruba translation is paragraph 61 in the source-docs. By doing so, it<br>will be easier to modify the translations when changes are made to the

<br>source-docs. This would imply some kind of web-based app to store and<br>manage the docs. I am looking at the way we translate in my<br>organization and thinking about what would be a good online tool to<br>coordinate translations. There are many proprietary tools with vast

<br>hoards of features and complications which cost 1-2 thousand dollars<br>per user, but they are not suitable for OLPC. I think OLPC docs-trans<br>would do well with a lighter, simpler application. If the list doesn't

<br>mind, I would like to post the resulting thoughts at a later date so<br>that there can be an exchange of ideas.<br><br><br>I apologize for the length, and I hope these ideas can be of help.<br><br>Micheal Cooper, Japan

<br>_______________________________________________<br>Devel mailing list<br><a href="mailto:Devel@lists.laptop.org">Devel@lists.laptop.org</a><br><a href="http://lists.laptop.org/listinfo/devel">http://lists.laptop.org/listinfo/devel

</a><br></blockquote></div><br><br clear="all"><br>-- <br>Todd Kelsey<br>630.808.6444