Devel Digest, Vol 20, Issue 22

[Todd Kelsey]

That sounds groovy. Perhaps you could open up a wiki page for each of the
sensible types of documentation you have suggested, and some of the
questions you suggested could be integrated on the pages in a
scope/objectives section.

-------------
 - Who are the intended readers of each doc?
 - What should be the range/ content of each doc?

It feels to me that from a scalability standpoint, each "type" of
documentation is ultimately going to need a community site sitting on a
multilingual cms so that it can scale out to different languages -- and
perhaps wiki can be extended to this purpose.

I think the parallel approach is wonderful. I am working with meadan (
www.meadan.org) on exploring a thing called TrIM, a multilingual instant
messaging technology that fascinated me when i first saw it in 2005, simply
because it displays the native and translated languages in parallel -- and
it feels like that could be a helpful tool on the laptops. (if anyone is
interested just ping me on gtalk -- I have a java file i can send you and we
can try it against a live translation database)

It's fascinating to consider documentation as a conversation -- but really
it is an asynchronous conversation, and if you want it to be excellent, it's
a two way conversation. that's a wonderful notion to make documentation
available in parallel -- the only thing i can think of is to slave a text
display tool to achieve the same kind of thing that MS Word does with
compare and merge -- where you can have exact scroll lock. that can't be too
hard to do. or maybe what you are implying is that publishing documentation
could include preparing for sharing in parallel views. very interesting.

one thing i am not clear on in terms of etiquette -- at what point should a
conversation like this be moved off the email list?

On 10/16/07, Micheal Cooper <cooper.me at gmail.com> wrote:
>
> > From: "Todd Kelsey" <tekelsey at gmail.com>
> > Subject: Re: slightly long and detailed proposal for
> >         documentation-translation       workflow
> ...
> > 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 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.
> >
>
> I agree completely.
>
> But it seems that this thread of the discussion is leading us to a
> list of what documentation is needed. The localization project is
> concerned with translating the strings used in the OS, and that is
> completely separate from user documentation. Don't you think we should
> come to consensus over:
> 1 - What docs are to be created?
> 2 - Who are the intended readers of each doc?
> 3 - What should be the range/ content of each doc?
>
> I think this should be our next step.
>
> So what kind of docs do we need? Just brainstorming:
> * - Teacher manual on hardware use and maintenance.
> * - Teacher manual on software use and lesson plans on instructing
> students on getting started.
> * - Technical manual for local support (really just teachers
> comfortable with the hardware and willing to help)
> * - User (student) manual that instructs on turning on the PC,
> locating controls, etc. Of course, this could be minimal to encourage
> discovery, or it could be a series of teasers that are intended to get
> the student started. They could be directions to do things without
> explanations of what is going to happen, i.e. "Click the pinwheel.
> What happened?"
>
> In the system for managing source-docs and translations, a useful
> option would be the ability to present (both in printing and online)
> facing pages of the source-doc/ English version and the target
> language translation. At some point, OLPC instructors are going to be
> in the field teaching teachers to use and teach the XO, and the docs
> themselves would be a common script for these interchanges. If the
> left page is English and the right page is the target language (with a
> one-to-one correspondence between sections), it would be much easier
> to communicate through the language barrier, even if the user of the
> target language speaks some English. We actually use this technique at
> my workplace, and it is indispensable.
> _______________________________________________
> 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/20071017/57380efb/attachment.html>