Devel Digest, Vol 20, Issue 22

[Micheal Cooper]

> 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.