[OLPC library] Documentation Update

Mon Jul 28 12:10:56 EDT 2008

I'd love for you to jump in with the edits - we've been talking about
that intro text for literally months, so feel free to edit. :)

I appreciate all the great ideas for organizing and adding content -
keep 'em coming. All are welcome to make edits. I've talked to Adam
Holt about incorporating some of the FAQ information, so I plan to add
Troubleshooting and Repairing sections as well.

About getting started with Floss Manuals itself - as a stopgap
measure, I've posted a screencast on using Floss Manuals to the Floss
Manuals blog, and Adam will re-encode it so it's not Flash dependent.
It's basically a walkthrough of getting started with Floss Manuals.
I'm sure we can arrange for sessions if anyone wants to get an
overview training session, too.

BookSprint planning is also moving along, and I have secured a
location here in Austin that should be wonderful up in the hills
overlooking the "river" (it's a lake, really). I'll be doing some tech
comm related networking to get some sponsored lunches and such, so
keep an eye out for those. We're talking with publishers as well and
the Floss Manuals toolset for printing is honestly one-of-a-kind,
probably the front runner for wiki content going to print-quality
output.

Thanks,
Anne

On Mon, Jul 28, 2008 at 11:00 AM,  <library-request at lists.laptop.org> wrote:
> Send Library mailing list submissions to
>        library at lists.laptop.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>        http://lists.laptop.org/listinfo/library
> or, via email, send a message with subject or body 'help' to
>        library-request at lists.laptop.org
>
> You can reach the person managing the list at
>        library-owner at lists.laptop.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Library digest..."
>
>
> Today's Topics:
>
>   1.  Good documentation: Inveneo training materials
>      (Christoph Derndorfer)
>   2. Re:  Documentation Update (Seth Woodworth) (Christoph Derndorfer)
>   3. Re:  Documentation Update (Seth Woodworth) (Seth Woodworth)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Mon, 28 Jul 2008 01:58:14 +0200
> From: Christoph Derndorfer <e0425826 at student.tuwien.ac.at>
> Subject: [OLPC library] Good documentation: Inveneo training materials
> To: library at lists.laptop.org
> Message-ID: <488D0B96.7080509 at student.tuwien.ac.at>
> Content-Type: text/plain; charset=ISO-8859-15; format=flowed
>
> Hi all,
>
> found some pretty sweet training lectures from Inveneo (www.inveneo.org):
>
> http://www.inveneo.org/icip-training/solutions/introduction.html
>
> Definitely something to keep in mind for our own documentation efforts.
> How cool would such a video-lecture being as a Sugar introduction? :-)
>
> Cheers,
> Christoph
>
> --
> Christoph Derndorfer
> Co-Editor
> OLPCnews, http://www.olpcnews.com
>
>
>
> ------------------------------
>
> Message: 2
> Date: Mon, 28 Jul 2008 03:38:03 +0200
> From: Christoph Derndorfer <e0425826 at student.tuwien.ac.at>
> Subject: Re: [OLPC library] Documentation Update (Seth Woodworth)
> To: library at lists.laptop.org
> Message-ID: <488D22FB.9000902 at student.tuwien.ac.at>
> Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>
> Hi all,
>
> tonight I've allowed myself to be somewhat inspired by ASUS'
> documentation for their eee PC901 series and here's my current
> suggestion for a TOC / skeleton that Seth mentioned in his previous
> message. I'm mainly using the current manual on FL
> (http://en.flossmanuals.net/OLPC_simple/Introduction) and Walter's
> Getting Started Guide
> (http://www.laptop.org/en/laptop/start/index.shtml) as main references
> here even though I'm of course aware that they're not necessarily 100%
> up-to-date, especially when it comes to 8.2 features and re-designs.
>
> [1] TOC
> [2] Introduction (based on FL's "Getting started with the XO")
> [3] Safety Precautions (using the cool black/white graphics that you see
> when shutting down an XO)
> [4] First steps
>    - installing the battery (FL Appendices: Replacing the battery or
> Walter's http://www.laptop.org/en/laptop/start/battery.shtml in a
> print-ready version)
>    - connecting the AC adapter to charge the battery (FL Appendices:
> Charging the XO battery)
>    - opening the XO (http://www.laptop.org/en/laptop/start/index.shtml
> with the cool graphics from
> http://en.flossmanuals.net/OLPC_simple/OpeningXO)
>    - power on (see link above)
> [5] Hardware Overview
>    - list of specifications
>    - features (http://www.laptop.org/en/laptop/start/features.shtml)
>    - ports (http://www.laptop.org/en/laptop/start/externalports.shtml)
>    - keyboard / touchpad (again, Walter's documentation at
> http://www.laptop.org/en/laptop/start/keyboard.shtml in a print-ready
> version)
> [6] First boot experience
>    - choosing name / color
> (http://en.flossmanuals.net/OLPC_simple/StartingXO)
>    - how to shutdown the machine
> [7] Overview of using the XO
>    - Home View (http://www.laptop.org/en/laptop/start/homeview.shtml)
>    - Neighborhood view
> (http://www.laptop.org/en/laptop/start/neighborhoodview.shtml ||
> http://sugarlabs.org/go/User:Walter/sandbox/Neighborhood)
>       - connecting to an access point
>    - Group view (something a little more detailed than what's currently
> available)
>    - Activity View
> (http://www.laptop.org/en/laptop/start/activityview.shtml)
>    - Frame (http://sugarlabs.org/go/User:Walter/sandbox/Frame)
>    - Journal (http://www.laptop.org/en/laptop/start/journal.shtml)
> [could this be moved to the activity tutorials section below?]
>    - keyboard shortcuts
>    - Updating the software (simpler and better version of
> http://wiki.laptop.org/go/Update_paths and
> http://en.flossmanuals.net/OLPC_simple/TuteUpdating - also with
> information on risks, xo-get, Bert's script, G1G1 packs, etc.)
> [8] Activity tutorials
>    - general intro about common features such as starting, closing,
> saving to journal, sharing, joining, etc.
>    - all the core activities explained in-depth
>    - updating activities (depending on progress of current development
> work for that feature)
>    - pointer to [[Activities]] on wiki.laptop.org
> [I] Troubleshooting
>    - common issues
> (http://www.laptop.org/en/laptop/start/troubleshooting.shtml / [[FAQ]])
>    - resources for more information (help@, wiki(s), forums, etc.)
> [II] References
>    - a ton of links to relevant information, wikis, Web sites,
> mailing-lists, forums, etc.)
>
> I hope this makes somewhat sense, if it doesn't then please attribute it
> to the late hour... ;-)
>
> Looking forward to your thoughts and feedback!
>
> Cheers,
> Christoph
>
> library-request at lists.laptop.org schrieb:
>> Message: 1
>> Date: Fri, 25 Jul 2008 19:32:35 -0400
>> From: "Seth Woodworth" <seth at laptop.org>
>> Subject: [OLPC library] Documentation Update
>> To: library <library at lists.laptop.org>
>> Message-ID:
>>       <b54bd10a0807251632n585ae36eo921225c6b90a41c3 at mail.gmail.com>
>> Content-Type: text/plain; charset="iso-8859-1"
>>
>> Hi everybody,
>>
>> I hope that everyone has joined the library list, from now on all
>> conversations should be out in public and on this list if at all possible.
>> I've been making some progress this last week on organizing things here at
>> OLPC and talking to several people individually.  But I apologize for not
>> emailing the list sooner to get the rest of us going.
>>
>> --Intro to FM--
>> I've been poking at the FLOSS Manuals site the past couple weeks, and while
>> it seems very straight forward, several people have expressed interest in an
>> introduction webcast from someone from FM or anyone else who understands the
>> system well.  I will get this organized for sometime in mid-week if that day
>> works for most involved.  There are a few people here at the office at the
>> very least that would like a chance to get their questions answered about
>> the system.
>>
>> --Action--
>> Our first action item is to move the old Getting-Started guide to FM for
>> overhaul.  There are many many current versions of GS and so far none of
>> them show off the new UI features upcoming in 8.2.0.  But Walter does have
>> some new UI versions of a few pages [1].  Screenshots for the new UI are
>> somewhat of a hairy issue, but I'll come to that.
>>
>> Each of GS' chapter should be Chapters at FM.  Someone will need to create
>> these as we go (I'm working on this now).  I am able to add new chapters via
>> this link [2] but I might have elevated permissions, I'll need to double
>> check this.  Once these documents are in FM's system there is going to be a
>> lot of work to do to structure them.
>>
>> --Flow and chapters--
>> A steering committee of volunteers, professional editors, staff members and
>> for goodness sakes someone who works with kids; is needed to figure out a
>> concise presentation of the Introductory information chapters.  Do we
>> introduce the interface first?  Do we introduce computers?  Does the journal
>> come before any given activity?
>>
>> This group needs to create a rough draft of what the information we give is
>> going to look like.  A structured table of contents and skeleton to build
>> from.  To simply write this document willy-nilly like our wiki isn't going
>> to result in the kind of document we are looking for.
>>
>> Let me know if you have a background that would lend itself to being a part
>> of this team and we'll start a conversation on the topic.
>>
>> --Other notes--
>>
>> * Reviewers
>> On his trip to SF Christoph was able to meet two volunteers that would like
>> to review our documentation for usability when we're done.  They are willing
>> to follow the instructions and see if they come upon any rough spots.
>>
>> * Conventions-
>> The conventions/Style Guide document is available [3].  If you would like to
>> make changes to it, let's discuss them on the library list before you make
>> changes.
>>
>>
>> Thank you everyone for your patience so far, and I will be more diligent in
>> the future about making all emails public via the library list.
>>
>>
>>
>> [1] http://sugarlabs.org/go/User:Walter/sandbox.
>> [2] http://en.flossmanuals.net/bin/view/OLPC_simple/WebHome (must login)
>> [3] http://en.flossmanuals.net/bin/view/OLPC_simple/WritingConventions
>> -------------- next part --------------
>> An HTML attachment was scrubbed...
>> URL: http://lists.laptop.org/pipermail/library/attachments/20080725/0cafb3df/attachment-0001.htm
>>
>> ------------------------------
>
> --
> Christoph Derndorfer
> Co-Editor
> OLPCnews, http://www.olpcnews.com
>
>
>
> ------------------------------
>
> Message: 3
> Date: Mon, 28 Jul 2008 04:20:28 -0400
> From: "Seth Woodworth" <seth.woodworth at gmail.com>
> Subject: Re: [OLPC library] Documentation Update (Seth Woodworth)
> To: "Christoph Derndorfer" <e0425826 at student.tuwien.ac.at>
> Cc: library at lists.laptop.org, Anne Gentle <annegentle at gmail.com>,       Ron
>        Hale-Evans <ludism at gmail.com>
> Message-ID:
>        <b54bd10a0807280120g4d8c96b6tcfe95cb92e41e078 at mail.gmail.com>
> Content-Type: text/plain; charset="iso-8859-1"
>
> Great start to the discussion.  Comments, suggestions, and additions
> in-line:
>
>
>> [1] TOC
>> [2] Introduction (based on FL's "Getting started with the XO")
>>
>
> I'm not too pleased with this text actually. It's legacy introduction that I
> don't really feel exemplifies the OLPC/Sugar project.  A good intro belongs
> here with some great photos from Peru or Mongolia, but with new text.
>
>
>> [3] Safety Precautions (using the cool black/white graphics that you see
>> when shutting down an XO)
>
>
> A 'page' on the subject, or perhaps a half page in our hypothetical physical
> structure.  I don't know the history of the iconic "Safety Precautions" nor
> how much they are based on reality. But I'm more than willing to be
> convinced otherwise.
>
>
>> [4] First steps
>>    - installing the battery (FL Appendices: Replacing the battery or
>> Walter's http://www.laptop.org/en/laptop/start/battery.shtml in a
>> print-ready version)
>>    - connecting the AC adapter to charge the battery (FL Appendices:
>> Charging the XO battery)
>>    - opening the XO (http://www.laptop.org/en/laptop/start/index.shtml
>> with the cool graphics from
>> http://en.flossmanuals.net/OLPC_simple/OpeningXO)
>>    - power on (see link above)
>
>
> This is the beauty of FM's remixing.  For first-boot documentation we can
> skip this section.  Presumably someone will have figured this out if they
> can view the docs.
>
> This is a good candidate for replacing the single fold page that was shipped
> with G1G1-v1
>
>
>> [5] Hardware Overview
>>    - list of specifications
>>    - features (http://www.laptop.org/en/laptop/start/features.shtml)
>>    - ports (http://www.laptop.org/en/laptop/start/externalports.shtml)
>>    - keyboard / touchpad (again, Walter's documentation at
>> http://www.laptop.org/en/laptop/start/keyboard.shtml in a print-ready
>> version)
>>
>
> I disagree for three reasons:
> 1.) Kids aren't going to grok or care
> 2.) We need to start talking about Sugar and the UI as soon as possible for
> people who are literally on their first boot
> 3.) It's the wrong philosophical to focus on the hardware and secs instead
> of the experience.  Also it brings up the opportunity for contrast with
> conventional machines in numbers that don't matter.
>
>
>> [6] First boot experience
>>    - choosing name / color
>> (http://en.flossmanuals.net/OLPC_simple/StartingXO)
>>    - how to shutdown the machine
>> [7] Overview of using the XO
>>    - Home View (http://www.laptop.org/en/laptop/start/homeview.shtml)
>>    - Neighborhood view
>
>
>
> This sounds about right, we can tweak the specifics further as we go of
> course.
>
> Everyone please critique this further!
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: http://lists.laptop.org/pipermail/library/attachments/20080728/dbf5ca83/attachment-0001.htm
>
> ------------------------------
>
> _______________________________________________
> Library mailing list
> Library at lists.laptop.org
> http://lists.laptop.org/listinfo/library
>
>
> End of Library Digest, Vol 16, Issue 22
> ***************************************
>