[OLPC library] Documentation Update (Seth Woodworth)

Sun Jul 27 21:38:03 EDT 2008

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