Documentation
OLPC hardware and software is designed to be discoverable so that a user can figure things out by experimentation. We are preparing teachers by extensively lecturing and writing about how the devices might be leveraged. The OLPC laptops will come with e-books documenting how to use them, and technical details needed by application developers are available on the web including this wiki.
Examples: see the user interface guidelines and a draft developers handbook.
There are many audiences for the laptops and their software and content; some of them may need to create their own instructional material, or their own versions of existing material. This wiki is open for development of such material. If you have created your own documentation -- for instance, text, screenshots, video or animation for the hardware or specific software that is being turned into an activity -- note it here.
TODO
We need to improve speed/accuracy of
() noting the need for pascals doc () making sure it gets created (*) integrating it with other such docs in a organizing framework () having an organizing framework () keeping the docs up to date / tagged with freshness indicators
Needs
- Comments in code -- clean up, write for children, translate, in synthesis make the code "readable" and localizable.
- Notes about development -- how to create a 'hello world' activity or bundle. This is intented to be in Activity_Template and others.
- Community introduction -- getting to know and collab with the social community of developers and supporting groups
- Packaging/downloading guide -- how to package, where to publish, how to find and download.(stable and unstable documentation)
- Testing guide -- how to write test plans, who tests, how to help test, how to read the results of automated / human tests.
- Build/release guide -- how builds are made how often, where they end up; stable v unstable; how an activity gets into a buld, how to build a costomized build.
- Fix and organize different types and pages of documentation that are spread in the wiki.
Specific examples
Educational materials
- Children Learning By Doing – Etoys on the OLPC XO an early draft of an introductory book about Etoys on the OLPC laptop for teachers and parents
- Essays and articles about math and science education, mainly using Etoys
In-activity documentation
- Etoys quick-guides (click the "?" icon in tool bar)
Wikitexts
- General introduction and user interface guidelines
- Emulating the OLPC environment on another computer
- The Sugar Architecture
- xo "how to" notes
- Introduction to Squeak Etoys on the BTest OLPC XO
- Materials done by me
Images/Pictures
- (from christina xu... to find on Flickr)
Tutorials
Videos
- User interface introduction
- social features introduction
- Etoys tutorial
- Etoys tutorials by Waveplace, (.ogg viewable on XO)
Notes
Current work
See the thread http://lists.laptop.org/pipermail/devel/2007-October/thread.html#7008 , especially http://lists.laptop.org/pipermail/devel/2007-October/007008.html .
Demo videos
Demonstration videos take much more space than text documents, but may be more accessible to pre-literate users, and require less translation.
Record a laptop being used. Creating such videos might be an interesting project for kids, and something for cross-school sharing.
Record a desktop session. This can provide clearer and smaller video, be simpler than recording someone using the laptop, and be more characteristics-of-user neutral. It can be mixed with video of someone using a laptop. Since only the screen can be seen, it can't be used to show physical manipulation of the laptop (pressing buttons, etc). Istanbul, the Gnome desktop session recorder, can be used to record the window of an emulated xo, or of a real xo with remote display. Recordmydesktop, is a command-line screencaster, which I have sucessfully used to record on an XO. Record a laptop's own screen. Alt-1 takes still screenshots. Perhaps we could set things up so users could also take video, making their own desktop session videos.
Lego - children's documentation done well
Lego building blocks do children's docs well. Cross culture and cross reading-ability (or "no" reading ability).
- http://www.lego.com/en-US/default.aspx
- http://www.lego.com/eng/buildinginstructions/
- Any in particular? MitchellNCharity 14:33, 16 October 2007 (EDT)
Some key points:
- Use of pictures (line drawings also, to exclude unimportant details)
- No reliance on prior knowledge of how things fit together or of systems thinking
- Task-based picture instruction to accomplish tasks while teaching systems thinking
Laptop CAD model for creating illustrations
A CAD model of the laptop exists. But is not yet public. It could be used to generate illustrations. http://dev.laptop.org/ticket/2650
Meetings
October 27 2007
11:30am-5pm EST
This agenda is for Saturday for anyone who ends up having a thought they think should be addressed and for the dynamic agenda. if you have some questions/thoughts, please add a section at the bottom of the document and indicate name after question/thought etc.
Notify when agenda/call is set up:
> michael cooper, dan samper, brent (todd contact)
Preshow Countdown (todd)
> cme, TrIM, integrating volunteers > miniads, characters/SL > laptop store, tour merch > parallels
Agenda
11:00-11:30 hello how are you 11:30-12:30 localization call 14:00-15:00 strategy and Q/A (Anne can attend at this time or earlier)
Ground to cover
> review of groups (doc, etc.) > status of translations, quotes, deadlines > strategy for commercial/open source.
Logistics
Voice conferencing solution?
Can we whip up an adobe connect professional account in time (purpose: to capture mtg for others and serve as precedent to capture future meetings as training/get acquainted for future people)
Questions
> What is the best way to determine dates and priorities for documentation? Are the children third priority, parents any priority as an audience, and are teachers first priority? > What priority should we make the technical staff, such as those keeping the school server running (is that just a subset of the teacher audience?) -Anne > Is a printed manual a possibility or even desired? -Anne > Should we try to write separate documentation for the school servers? - Anne > How is laptop.org currently recognizing contributions on a personal level and on a company level? Would it help to put together a "request for sponsorship" for translation, illustrations, or template design? -Anne > Does laptop.org have a set of design guidelines? If we were to request creation of print/PDF templates, would the designer work with the website designers? Is there a need for consistent messaging from laptop.org? -Anne > How can we maintain a relationship with the documentation person that laptop.org hires (not duplicating work, communicate with him or her, and so on)? - Anne
Simplified User Guide
A redeveloped version of the original build 542 notes that has been edited and expanded.
- Simplified User Guide page.
Handbook
A handbook for developers, teachers, contributors, and laptop-users. For other handbooks and higher-level discussion, see Documentation.
Background
OLPC is an education project for children, building tools for stimulating children's creativity, starting with a children's laptop, a child-friendly desktop interface, and communities of learning and creation dedicated to children's education around the world.
How can I get involved?
Who works on OLPC?
Designers, hardware manufacturers, firmware developers (Men Of FORTH), Linux kernel and systems developers, activity developers (esp python, javascript, actionscript, C), database and interface designers, localization fanatics, game developers, authors, translators, artists, musicians, media encoding experts...
Where does everyone hang out?
Developers primarily hang out on a few IRC channels : #sugar for activity and interface development, #olpc for general discussion and OS/kernel hacking, #olpc-content for content and library development and localization.
Community members have a few other channels : #olpc-es for spanish-language discussion, and low-traffic channels for specific pilots and countries (peru, brasil).
The OLPC wiki has a lot of means of knowing how and why to do things related to the xo.
Sugar
Emulating Sugar
jhbuild
VMWare and QEMU
- See Emulation
Sugar Activities and Bundles
- If you want to do a activity please start seeing Activity Template
Bundle formats
- See Content bundles and activity bundles
Example Activities
Other example bundles
