Documentation: Difference between revisions

From OLPC
Jump to navigation Jump to search
(+Demo videos)
m (→‎Simplified User Guide: avoid redirect)
 
(52 intermediate revisions by 17 users not shown)
Line 1: Line 1:
{{Obsolete|link=[[Manuals]]}}
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.


''This page was for thinking about documentation needs and opportunities in 2007.''
'''Examples''': see [[Guidelines|the user interface guidelines]] and [[Handbook|a draft developers handbook]].

OLPC [[hardware]] and [[software]] are designed to be discoverable so that a user can figure things out by experimentation, but there are still a few things that [[Teacher Training|teachers]] need to be taught how to show the children. We are preparing teachers by extensively lecturing and writing about how the devices might be leveraged. That material needs to be gathered and organized. 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 [[Guidelines|the user interface guidelines]]


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.
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.
Line 12: Line 16:
() having an organizing framework
() having an organizing framework
() keeping the docs up to date / tagged with freshness indicators
() keeping the docs up to date / tagged with freshness indicators

==Volunteers==

OLPC is planning to hire a Documentation Lead to get these projects organized. In the meantime, why don't we just do it? Please add your signature if you are working on any documentation, and tell us what you are working on.

* --[[User:Mokurai|Mokurai]] 13:37, 13 November 2007 (EST) My outlines are at [[OLPC Publications]]. Unofficial, so far. Please add, edit, argue, etc.
* -- [[User:Annegentle|annegentle]] 17:34, 13 July 2008 (UTC) Working on kids/parents/teachers/eventually programmer documentation for XO, Sugar, and Activities, at [[FlossManuals|http://flossmanuals.net]]


== Needs ==
== Needs ==

* Comments in code -- clean up, write for children, translate, in synthesis make the code "readable" and localizable.
Don't just make suggestions. Improve the many documents and pages we have.
* 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
* [[Comments in code]] -- clean up, write for children, translate, in synthesis make the code "readable" and able to be localized.
* 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.
* Notes about development -- how to create a 'hello world' activity or bundle. This is intended to be in [[Activity Template]] and others.
* [[Community]] introduction -- getting to know and collaborate with the social community of developers and supporting groups
* 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.
* [[Packaging/downloading guide]] -- how to package, where to publish, how to find and download.(stable and unstable documentation), how to make ISOs for live CDs.
* [[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 build, how to build a customized build.
* Fix and organize different types and pages of documentation that are spread in the wiki.
* Fix and organize different types and pages of documentation that are spread in the wiki.


== Specific examples ==
== Specific examples ==
=== Educational materials ===
* [http://www.laptop.org/OLPCEtoys.pdf 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
* [http://www.squeakland.org/school/HTML/essays/essays.html Essays and articles] about math and science education, mainly using Etoys

=== In-activity documentation ===
* [[Etoys]] quick-guides (click the "?" icon in tool bar)

=== Wikitexts ===
=== Wikitexts ===
* [[Guidelines|General introduction]] and user interface guidelines
* [[Guidelines|General introduction]] and user interface guidelines
Line 28: Line 49:
* The [[Sugar Architecture]]
* The [[Sugar Architecture]]
* [[xo "how to" notes]]
* [[xo "how to" notes]]
* [[Sugar_Etoys | Introduction to Squeak Etoys on the BTest OLPC XO]]
* [[User:HoboPrimate/manual | Materials done by me]]


=== Images/Pictures ===
=== Images/Pictures ===
* (from christina xu... to find on Flickr)
* [http://www.flickr.com/groups/olpc/ OLPC group on Flickr]
* [http://www.flickr.com/groups/xophotos/ XO photos group on Flickr]

===Blog entries ===
* [http://dfwxo.blogspot.com/2008/02/today-amy-walker-1st-grade-teacher-in.html First grade students experience the XO laptop (Dallas-Forth Worth, Texas)]
* [http://justwriteclick.com/2008/03/02/taking-the-one-laptop-per-child-xo-laptop-to-the-preschool-classroom/ Taking the One Laptop Per Child XO laptop to the preschool classroom (Austin, Texas)]



=== Tutorials ===
=== Tutorials ===
* [[Forth Lessons]]
* [[Forth Lessons]]
* [[Activity tutorial]]
* [[Activity bundles]]
* [[Executable Math]]


=== Videos ===
=== Videos ===
* [http://www.youtube.com/watch?v=MShr7ZHsOfI&mode=related&search= Etoys tutorial]
* [http://www.youtube.com/watch?v=5sHzq5eOxdg&mode=related&search= User interface introduction]
* [http://www.youtube.com/watch?v=5sHzq5eOxdg&mode=related&search= User interface introduction]
* [http://www.youtube.com/watch?v=BAPHhGoq2OI&mode=related&search= social features introduction]
* [http://www.youtube.com/watch?v=BAPHhGoq2OI&mode=related&search= social features introduction]
* [http://www.youtube.com/watch?v=MShr7ZHsOfI&mode=related&search= Etoys tutorial]
* [http://www.waveplace.net/resources/tutorials/ Etoys tutorials] by Waveplace, (.ogg viewable on XO)


== Demo videos ==
=== 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
Demonstration videos take much more space than text documents, but may be more accessible to
Line 57: Line 95:
[http://live.gnome.org/Istanbul Istanbul], the Gnome desktop session recorder,
[http://live.gnome.org/Istanbul 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]].
can be used to record the window of an emulated xo, or of a real xo with [[remote display]].
[http://recordmydesktop.iovar.org/about.php 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
''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.
could also take video, making their own desktop session videos.


=== Lego - children's documentation done well ===
[[Category:Learning]]

[[Category:Developers]]
Lego building blocks do children's docs well. Cross culture and cross reading-ability (or "no" reading ability).
[[Category:Sugar]]

[[Category:HowTo]]
:http://www.lego.com/en-US/default.aspx
{{cleanup}}
:http://www.lego.com/eng/buildinginstructions/
::Any in particular? [[User:MitchellNCharity|MitchellNCharity]] 14:33, 16 October 2007 (EDT)
:: I like the Lego MindStorms for the use of pictures, use of screenshots, use of project ideas, and also explaining technical programming concepts with few words. Also see building instructions like the Mission to Mars book - example below.
[[Image:Lego_page.JPG]]

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

Roy Doty's long-running column [http://www.roydoty.com/syndicated/wordless-panel.htm Wordless Workshop] is another excellent model for what we need to do.

=== 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, Bbrent (Todd to 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 Gentle 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.

'''Meeting notes'''
Notes are available at [[Xodoc localization mtg notes 102707]]

== Simplified user guide ==
''From 2008'', the original build 542 demo notes edited and expanded.
* [[Simplified user guide]]

== Background ==
[[OLPC]] is an [[educators|education]] project for children, building tools for stimulating children's creativity, starting with a children's [[xo|laptop]], a child-friendly [[sugar|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 : <tt>#sugar</tt> for activity and interface development, <tt>#olpc</tt> for general discussion and OS/kernel hacking, <tt>#olpc-content</tt> for content and library development and localization.

Community members have a few other channels : <tt>#olpc-es</tt> 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.

== Emulating Sugar ==
=== jhbuild ===
* See[[Sugar with 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 ===
* [[kuku]]

Latest revision as of 00:11, 4 November 2011

542-stopicon.png This page has a more up-to-date location: Manuals


This page was for thinking about documentation needs and opportunities in 2007.

OLPC hardware and software are designed to be discoverable so that a user can figure things out by experimentation, but there are still a few things that teachers need to be taught how to show the children. We are preparing teachers by extensively lecturing and writing about how the devices might be leveraged. That material needs to be gathered and organized. 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

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

Volunteers

OLPC is planning to hire a Documentation Lead to get these projects organized. In the meantime, why don't we just do it? Please add your signature if you are working on any documentation, and tell us what you are working on.

  • --Mokurai 13:37, 13 November 2007 (EST) My outlines are at OLPC Publications. Unofficial, so far. Please add, edit, argue, etc.
  • -- annegentle 17:34, 13 July 2008 (UTC) Working on kids/parents/teachers/eventually programmer documentation for XO, Sugar, and Activities, at http://flossmanuals.net

Needs

Don't just make suggestions. Improve the many documents and pages we have.

  • Comments in code -- clean up, write for children, translate, in synthesis make the code "readable" and able to be localized.
  • Notes about development -- how to create a 'hello world' activity or bundle. This is intended to be in Activity Template and others.
  • Community introduction -- getting to know and collaborate 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), how to make ISOs for live CDs.
  • 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 build, how to build a customized build.
  • Fix and organize different types and pages of documentation that are spread in the wiki.

Specific examples

Educational materials

In-activity documentation

  • Etoys quick-guides (click the "?" icon in tool bar)

Wikitexts

Images/Pictures

Blog entries


Tutorials

Videos

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)
I like the Lego MindStorms for the use of pictures, use of screenshots, use of project ideas, and also explaining technical programming concepts with few words. Also see building instructions like the Mission to Mars book - example below.

Lego page.JPG

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

Roy Doty's long-running column Wordless Workshop is another excellent model for what we need to do.

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, Bbrent (Todd to 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 Gentle 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.

Meeting notes Notes are available at Xodoc localization mtg notes 102707

Simplified user guide

From 2008, the original build 542 demo notes edited and expanded.

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.

Emulating Sugar

jhbuild

VMWare and QEMU

Sugar Activities and Bundles

Bundle formats

Example Activities