slightly long and detailed proposal for documentation-translation workflow

Todd Kelsey tekelsey at gmail.com
Tue Oct 16 16:10:45 EDT 2007


fyi val scarlata and i went back through material to try and make something
more user friendly. she scanned through wiki and assembled various links as
good cop, then I played bad cop to try and control scope, she had a
documentation party with a couple of students to assemble material -- and
now three tech writers who have volunteered are working very much on trying
to make it user friendly (and extensible to incorporate software flux, and
adaptable into various languages). There is a proto google doc that anyone
who is interested is welcome to view, join in, or if you email me i'll send
a pdf. haven't had time to situate in wiki yet.

I saw marklogic do very nice work with x-query allowing people to
self-assemble their own books on the fly. i think this is how safari u. does
things. kind of like alacarte ebooks. it would be cool if flowr foundation
(open source x-query) could help put something like that together. but that
would be porsche -- it would be nice just to have a scalable system period
-- and that's what we're working on.

On 10/16/07, Polychronis Ypodimatopoulos <ypod at mit.edu> wrote:
>
> heh, I totally agree, but this doesn't mean that there isn't a market
> for a book like that (unfortunately!).
>
> Apart from the fact that some people feel "disabled" without a book,
> there still is *not* a "user-friendly" introduction on how to use the
> laptop (let alone how it works) and I doubt that there will be one
> anytime soon because OLPC's primary mission is not to sell the XO in the
> US market. However, I'm afraid that OLPC will have to deal with ....
> user support! I hate to say this but there were already a couple of
> people visiting the lab, asking about where to buy the laptops and
> whether they're good for their needs.
>
> Pol
>
> Mitch Bradley wrote:
> > At the current rate of XO software churn, any printed book will be
> > obsolete/inaccurate before the ink is dry.
> >
> > Todd Kelsey wrote:
> >
> >> I have been struggling with my literary agent and trying to knock
> >> someone over the head with a wet noodle into realizing that there
> >> *will* be a market for a book, and trying to suggest going with an
> >> e-book, with editorial support from a publisher, put it on amazon,
> >> develop the whole thing in a robust authoring cms so updates and
> >> multilingual versions can be easily made. one publisher responded with
> >> fear, blah blah blah, and I made an attempt to provide rationales
> >> (including insights from Wikinomics, which has helped me to be able to
> >> articulate some of the value propositions), but I'm 2 degrees away
> >> from throwing in the towel, and inviting whoever wants to join me in
> >> making a multimodal community book. then maybe when the publishers
> >> wake up they could license it and use their distribution channels to
> >> put it in stores.
> >>
> >> I don't know if the publishers realize how cool the little green xo is
> >> as a way for people to get acquainted with Linux.
> >>
> >> Ok I'm throwing in the towel. We could call it the Hitchhiker's Guide
> >> to the Laptop. I don't care what the title is. The community could
> >> name it, write it. If anyone is interested in helping learners who
> >> desire a book to get acquainted with the very wonderful work you are
> >> doing, please feel free to get in touch.
> >>
> >> Maybe the proceeds from the book could go towards a series of laptop
> >> libraries where the laptops could be checked out by kids.
> >>
> >> I guess in the same time it took to write this email I could have
> >> written a wiki page.
> >>
> >> On 10/16/07, *Steve Fullerton* <fullerton.steve at gmail.com
> >> <mailto:fullerton.steve at gmail.com>> wrote:
> >>
> >>     Good points.  The OLPC is designed around collaboration.  The
> >>     model really works well where every child in a class has his/her
> >>     own laptop, uses it in and out of school, and lives in close
> >>     enough proximity to other class members to make the Mesh work.  In
> >>     class one kid discovers how to do something and teaches the other
> >>     kids (and teachers as well).
> >>
> >>     In an address at Harvard Law, Negroponte said something like:
> >>     "People ask me who is going to teach the teachers to teach the
> >>     children how to use the XOs  --- and I wonder what planet are they
> >>     on? ..."
> >>
> >>     A child who gets one through G1G1 in isolation will not be able to
> >>     fully benefit from collaboration and thus, along with
> >>     parent/tutor, would definately benefit from user documentation in
> >>     lieu of help from others in class.  Likewise, the Carlos Slims
> >>     approach of putting them in Mexican libraries.
> >>
> >>     If G1G1 goes big-time in November, you can sure bet that there
> >>     will be "OLPC for Dummies" books, etc. by Christmas.
> >>
> >>     On 10/15/07, *Todd Kelsey * <tekelsey at gmail.com
> >>     <mailto:tekelsey at gmail.com>> wrote:
> >>
> >>         I am amazed and inspired by all the wonderful projects and
> >>         activities that have arisen from the laptop project -- and
> >>         though I was skeptical at first, I have also come to
> >>         appreciate the constructivist approach to education; I didn't
> >>         "get it" until I came to appreciate the notion of allowing
> >>         children to come to "aha" moments on their own. The fact that
> >>         children do fine without manuals at the present level of
> >>         interaction is a testament to the design of the computer and
> >>         the philosophy behind it. As generation xo grows older, I
> >>         think they will want to get deeper into the systems, and as
> >>         they do, I think they will want more information, and I'd like
> >>         to help make that freely available.
> >>
> >>         I think a user manual or documentation will be more helpful
> >>         for adult learners who will end up participating in the laptop
> >>         community, and who would find it helpful to have something to
> >>         refer to. Perhaps users could learn many things simply by
> >>         exploring, and yet they might appreciate having something to
> >>         turn to. Other people may not have personal possession of a
> >>         laptop, but would be interested in learning how they could
> >>         support the project. Some people who order the laptops through
> >>         www.xogiving.org <http://www.xogiving.org> will get frustrated
> >>         with the laptop if they have no resources to turn to, and I'd
> >>         like to help them have fun.
> >>
> >>         I think the idea of  encouraging children to help each other
> >>         learn is wonderful;  I also appreciate the principle of
> >>         inclusiveness, and I think that one way to be inclusive is to
> >>         address various learning styles.
> >>
> >>
> >>         On 10/15/07, *Steve Fullerton* < fullerton.steve at gmail.com
> >>         <mailto:fullerton.steve at gmail.com>> wrote:
> >>
> >>             Hi Ed and all,
> >>
> >>             I fully appreciate the detail.  However, IMHO I think that
> >>             there is some re-thinking required re: the traditional
> >>             "user" documentation.  The core  of the OLPC (literally
> >>             one laptop per child; the model does not work as well if
> >>             there is not possession of a laptop for each child) is
> >>             that of collaboration.
> >>
> >>             One child learning something and then teaching his/her
> >>             classmates. OLPC machines are not meant to be used in
> >>             isolation.  You could actually make a credible argument
> >>             that user manuals are bad for the project.
> >>
> >>             The highly intuitive design of Sugar and the experience of
> >>             the pilots bears this out.  The children seem to do just
> >>             great without manuals,  discovery is enhanced, and many of
> >>             the constructionist ideals are realized.
> >>
> >>             What do you think?
> >>
> >>
> >>             On 10/15/07, *Ed Trager* < ed.trager at gmail.com
> >>             <mailto:ed.trager at gmail.com>> wrote:
> >>
> >>                 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
> >>                 _______________________________________________
> >>                 Devel mailing list
> >>                 Devel at lists.laptop.org <mailto:Devel at lists.laptop.org>
> >>                 http://lists.laptop.org/listinfo/devel
> >>
> >>
> >>
> >>
> >>             --
> >>             Regards,
> >>
> >>             Steve
> >>             ____________________________
> >>             Steven C. Fullerton
> >>             email: fullerton.steve at gmail.com
> >>             <mailto:fullerton.steve at gmail.com>
> >>             cell/voice mail: 619.339.9116
> >>             ____________________________
> >>             _______________________________________________
> >>             Devel mailing list
> >>             Devel at lists.laptop.org <mailto:Devel at lists.laptop.org>
> >>             http://lists.laptop.org/listinfo/devel
> >>
> >>
> >>
> >>
> >>         --
> >>         Todd Kelsey
> >>         630.808.6444
> >>
> >>
> >>
> >>
> >>     --
> >>     Regards,
> >>
> >>     Steve
> >>     ____________________________
> >>     Steven C. Fullerton
> >>     email: fullerton.steve at gmail.com <mailto:fullerton.steve at gmail.com>
> >>     cell/voice mail: 619.339.9116
> >>     ____________________________
> >>
> >>
> >>
> >>
> >> --
> >> Todd Kelsey
> >> 630.808.6444
> >>
> ------------------------------------------------------------------------
> >>
> >> _______________________________________________
> >> Devel mailing list
> >> Devel at lists.laptop.org
> >> http://lists.laptop.org/listinfo/devel
> >>
> >>
> >
> > _______________________________________________
> > Devel mailing list
> > Devel at lists.laptop.org
> > http://lists.laptop.org/listinfo/devel
> >
> _______________________________________________
> Devel mailing list
> Devel at lists.laptop.org
> http://lists.laptop.org/listinfo/devel
>



-- 
Todd Kelsey
630.808.6444
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.laptop.org/pipermail/devel/attachments/20071016/a9c3c947/attachment-0001.htm 


More information about the Devel mailing list