[OLPC library] goal setting and scope for BookSprint

[Anne Gentle]

Hi John,
Thanks for the feedback. You bring up very good points.

> The School Server needs a complete documentation package:
>  - Installation Guide
>  - Administrator's Guide
>  - Troubleshooting
>
> We already have two separate User's Guides for the laptop, but nothing
> for the school server...  (We could say the same about the software!)

Thanks so much for this input. We can re-prioritize if necessary to
accommodate this request.

>
>> 2. Add:
>> Troubleshooting (esp. for connectivity)
>
> A lot of effort already went into a hardware troubleshooting manual,
> and it is already translated into Spanish and being field tested.
> See http://wiki.laptop.org/go/XO_Troubleshooting_Guide
> Please don't duplicate, move, or fork this effort.

We're aware of the dissasmbly, repair, and troubleshooting sections
you mention and intend to leverage them fully. For some of the
information, the goal is to use the FLOSS Manuals API to embed it back
into wiki.laptop.org. It's good to know that some people at laptop.org
are not aware of this intention.

As Adam said, FLOSS Manuals has been selected for all docs, especially
docs that can be shipped with the OS. FLOSS Manuals gives us the
ability to remix the content so that it can be included on a shipped
XO laptop (or any hardware that Sugar runs on). There is work to put a
"first boot" assistance Activity and FLOSS Manuals can provide the
formats needed for that task. Another Activity related to the
first-boot scenario should provide user assistance, and FLOSS can
provide the content for that Activity.

> On the other hand, there is absolutely no software troubleshooting
> (outside of http://wiki.laptop.org/go/Startup_Diagnosis), as any repair
> center will just reload the OS & activities upon encountering
> a software problem.   This is a gaping hole in documentation....

While I agree with this assessment, I am not certain that we have
BookSprint team members who could write this information beyond what
is available on that wiki.laptop.org/go/Startup_Diagnosis. And for our
audience (kids/parents/teachers), that page may be sufficient. Thanks
for pointing it out.

> The connectivity troubleshooting still needs writing, but you have to
> include the school server to write that story.
>
>> Repair (dis-assembly with photos)
>
> Repair is not disassembly.
> We already have disassembly instructions, at:
> http://wiki.laptop.org/go/Disassembly

Yes, sorry for my imprecise parens that can be misinterpreted. I mean
that disassembly is included as part of Repair.

> Repair instructions are included as part of the Troubleshooting guide
> (which references the Disassembly Guide).

This type of embedding is where FLOSS Manuals shines. This type of
information is perfect for remixing.

> I was disappointed that the translation system being used for activities and
> Sugar wasn't also available for helping on wiki translation...   Are you
> adding
> a third system, or using an existing one ?

Yes, that is disappointing isn't it? I am hoping to ensure that
translators know that the Pootle system files should be used to
maintain a consistent vocabulary. I wouldn't call FLOSS Manuals a
third system, it is "just" a wiki like wiki.laptop.org, but it offers
a feature set that enables us to deliver the exact type of files
needed to ship user assitance on the laptop.

Sugar Labs approached FM for its own documentation needs, since they
are separate from OLPC, so FLOSS Manuals is a good solution to the
separation of hardware and software.

Thanks for helping shape our week. I hope these responses help outline
the needs we're meeting here.

Thanks,
Anne