XO doc and the journey to wiki-fied documentation

Just wanted to give another update on the happenings in the end-user doc front from my neck of the woods. (Idioms sprinkled throughout!)

I got an HTML copy to SJ and a second copy with an Index and some customizations on the CSS. I tested it on an XO emulation and the Browse Activity does really well with the Index and search so I’m pleased with the results.

Here’s what it looks like when you view it on an XO in the Browse Activity (click on the image to see it full-sized).

XO Quick Start

I’ve written a letter of appreciation to Author-it for giving us the license and ability to do quick rearranging. It’s coming in handy.

Adam Hyde of FlossManuals.net and I met to talk about a migration path for the kids end-user doc content at http://wiki.laptop.org/go/Simplified_user_guide. They’ve just finished a lot of translation work so that we can also have multiple language versions of the simple user guide on the FM site and translators could work in a side-by-side view which is nice. The next steps are for me to re-arrange the content in Author-it into an outline closer to the structure that FM uses (Introduction, Installing, Interface, Tutorials, Appendices). Once I get the new structure to the content, Adam and I and anyone else who wants to pitch in can do copy and paste of the HTML into the FM pages. Adam’s filling out the infrastructure on FM now here:

From Adam I learned that the formatting of the print versions out of the Floss Manuals wiki uses Scribus – http://www.scribus.net/. It’s an open source page layout and publishing tool.

Also, I have had a few people contact me this week to see how they can help so I’ve sent them the information about the different groups for the different user guides from the wiki.laptop.org/go/Manuals page. Here are the basics for how to help.

  1. Join the Library list at http://lists.laptop.org/listinfo/library where documentation discussions occur.
  2. Sign up for an OLPC wiki account at wiki.laptop.org.
  3. Download and install an emulator. (optional, but helpful) QEMU is an open source processor emulator that can emulate an entire PC, including its peripheral devices like the disk, display, network, and so on. You must download and install this package to emulate the XO laptop.
  4. Become familiar with the Simplified User Guide at http://wiki.laptop.org/go/Simplified_user_guide and read about the audiences at http://wiki.laptop.org/go/Manual.
  5. Feel free to edit or start a new page with a new audience in mind. Note that we are porting the kids manual to Flossmanuals.net so also become familiar with their structure.

I’ve also started an Educator’s Guide at http://wiki.laptop.org/go/Educators_guide . I am way out of my league writing about constructivism and intervention guides (lesson plans) but I figure I have to start somewhere. I also want to link to as many additional reading materials about constructivism and how to teach with that learning theory in the forefront. There’s a nice post over at OLPC News that has great reading materials and ideas for accessories. I’ll also study the http://wiki.laptop.org/go/Educational_activity_ideas page as well.

I still have some edits that I need to do to the Simplified user guide wiki page, and I really want to re-write the interface instructions (or someone else could if they are feeling energetic.) I recently re-wrote the instructions for installing a new activity with screenshots from Update.1 for each. So I’m now able to run Update.1 in my emulation environment.

I’m also working with people who have worked on the artwork. There are some talented artists giving their time to the project.

The journey to Floss Manuals is going to be interesting for several reasons. One is, which wiki is source? Floss Manuals or wiki.laptop.org? Adam and I will likely have to get notifications on each wiki and attempt to keep them synced. I’m also trying to design for re-use because it’s easy to remix manuals in Floss Manuals. So there should be a way to use content from the simplifed user guide where kids are the audience for the teacher or instructor’s guide. The translation workflow in Floss Manuals lets the translator view both text side by side, which will be helpful I believe, but there’s no translation memory.

Another observation – my perception is that OLPC really wants the wiki.laptop.org to be the single place to get information. A recent status update encouraged the developers to make sure their Activity wiki pages are clean, neat, up-to-date, and accurate. However, there is a nice set of topics at laptop.org/start that the Give1Get1 participants are pointed to in the letter they receive when opening their XO laptop box. (Thanks to whurley for posting his xo unboxing photos on flickr.)olpc_letter.jpg

Since I think it is a good idea to have these separate pages, my perception is that there is definitely a limit to what the wiki can do for the general public (although I would qualify that statement by saying that most XO participants are not the general public.) The laptop.org/start pages are an excellent design and clearly written with an easy-to-use navigation system. I’d love to find out the page hits and find out if there’s any way to measure effectiveness of those pages versus the wiki pages (or the wiki as a whole).


  • January 6, 2008 - 8:58 pm | Permalink

    I love the headings of ‘what am I learning’ and ‘why is this important’.

    Then again, I am a dad who sometimes has to explain why play is so important to others.

  • January 8, 2008 - 9:35 pm | Permalink

    I’m glad to hear that! Those weren’t always easy to write, surprisingly.

    We have an XO laptop now, and my four-year-old son is very happy to have a “special computer just for me” after I explained to him that it was built just for kids. Seeing him get a kick out of Turtle Art makes me grin every time – you build a set of commands that click together like a puzzle and the turtle draws lines based on your puzzle pieces. Even Mom can play that game. :)

  • Leave a Reply