Updated battery repair documentation
Hi, I've just published a rewrite of the battery troubleshooting/repair documentation at http://wiki.laptop.org/go/XO_Troubleshooting_Battery This is based on recent experiences of battery repair with the help of Richard Smith, adding new techniques and solutions. Also, I restructured the content so that the page is more approachable when you have a broken battery in your hands, and so that the content is more succinct. Follow the "Start here" instructions step by step and it'll take you to the appropriate section regarding the failure condition that you're dealing with. Another change is that all the content related to diagnosing power/battery problems that are actually related to problems outside of the battery has been moved here: http://wiki.laptop.org/go/XO_Troubleshooting_Power to further improve readability. (maybe this new Power page needs a bit of work and more content - help appreciated) Thanks! Daniel ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Documentation
While on the topic of lack of documentation, I would like to thank John Gilmore for reminding us about unfulfilled promises and Harald Welte for working with Via to get the Programmer's Guide to the VX855 Companion Chip used in XO-1.5 publicly released. It is linked into the XO-1.5 wiki page: http://wiki.laptop.org/go/XO-1.5#Core_electronics Cheers, wad ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
OS Builder -- updated documentation: fiddle config files, run on XO
Apologies about the spam, but this will probably be of interest to people using OOB currently to prep things for XO deployments (XO-1.75 deployments! yay!). http://wiki.laptop.org/go/OS_Builder -- see the Recipes section. enjoy, m -- mar...@laptop.org -- Software Architect - OLPC - ask interesting questions - don't get distracted with shiny stuff - working code first - http://wiki.laptop.org/go/User:Martinlanghoff ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Wiki documentation updated
Hi, I've been working on the wiki content: Lots of obsolete content deleted, replaced with redirects or textual links to current information. Where the obsolete content describes strategy or non-obvious technical processes, I've left it in place (or put on "Historical" pages) as it might be useful in the future - but the information is clearly marked as obsolete with links to where the new info is found. Lots of duplicate info was removed, being replaced with links the the one definitive place where relevant. Some pages were consolidated too. I've written some procedures into emails too many times -- now they are wikified. Also, some processes that were only known in the minds of a select few of us (such as operation of mock.laptop.org, how the dropbox system works, etc) are now documented. I've documented how the current release process is working, and I've added source and maintainer info for all of our software components. Hopefully it is now a bit easier for new contributors to get involved on system-level development and release engineering. Pages with new, interesting content: Build System Image Builder RPM Dropbox Project hosting Release Process Release Process/* Frozen repositories Kernel dracut-modules-olpc User:DanielDrake/Yum User:DanielDrake/Language_packs Serial adapters Developers Developers/* Generic maintenance/minor updates: Taking_a_Joyride Joyride Emulating the XO Emulating_the_XO/Comparison_of_Alternatives Building_custom_images Releases Future releases USR_Checklist Unscheduled_software_release_process Release Notes F11 for 1.5 F11 for 1.0 9.1.0 Feature requests Feature roadmap What_release_am_I_running%3F How_to_check_the_OS_and_firmware_versions Updating the XO OS Images Builds olpc-update olpc-contents Mailing lists olpc-library Communication channels Developer key Debian initramfs Building initramfs Initramfs Developer mailing lists olpc-switch-desktop olpc-netutils olpc-bootanim PolicyKit-olpc olpc-runin-tests ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
[Server-devel] documentation for customizing XS ISO
Hi, I thought I saw some "official" documentation once for how deployments can customize kickstart, add more packages, etc. Can't find it now. Was I dreaming? We're hitting various roadblocks in La Rioja and I'd like to make sure we're following what's documented, and that the docs are correct. Right now we are struggling because installation media is not available during %post. Thanks, Daniel ___ Server-devel mailing list server-de...@lists.laptop.org http://lists.laptop.org/listinfo/server-devel
Wake on ARP support on XO-1: libertas documentation
Hi! I've recently been trying to add Wake-on-ARP support (using the ethtool interface) for the XO-1. I failed badly: no wake happened at all (not even unicast) and a libertas reset was required after resume. Is there any reliable documentation about how to configure wakeup packet filters on our version (*) of libertas? The libertas documentation [1] specifies a simple extension to CMD_802_11_HOST_SLEEP_CFG, but for 88W8385 and 88W8399 only (XO-1 has 88W8388). The current driver in the OLPC kernel has code that looks a lot like the one in OLPC#6993 [2], though the iwpriv part is missing. I based my code on the patch and examples from #6993, but as mentioned it (non-permanently) kills the 8388; apparently as soon as I pass a non-NULL p_wol_config to lbs_host_sleep_cfg(). Also I don't understand how the examples were constructed: The location part of the signature matches neither IEEE 802.11 data frames nor IEEE 802.2 ethernet frames. Does libertas use some custom internal representation for received frames and if so, what does it look like? (*) I'm using usb8388-5.110.22.p23.bin, md5sum 5e38f55719df3d0c58dd3bd02575a09c, from http://dev.laptop.org/pub/firmware/libertas/ [1] http://wiki.laptop.org/images/f/f3/Firmware-Spec-v5.1-MV-S103752-00.pdf [2] http://dev.laptop.org/ticket/6993 CU Sascha -- http://sascha.silbe.org/ http://www.infra-silbe.de/ signature.asc Description: Digital signature ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
"Sensor mode" documentation
Hi! Can anyone point me to some documentation about the various "sensor modes" of the XO-1 microphone input, please? I'm trying to figure out why Measure sets the volume to different values for left/right channel. According to the hardware specs it should be a mono input anyway... Already tried wiki.laptop.org and the hardware specs (CL1_Hdwe_Design_Spec.pdf), but what I found was rather sparse. E.g. the specs talk about programmable input gain of 0/10/20/30dB, but alsamixer only shows a 20dB switch... CU Sascha -- http://sascha.silbe.org/ http://www.infra-silbe.de/ signature.asc Description: Digital signature ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Server-devel] [sugar] Restoring journal entries (was Re: Backup And Restore Feature Documentation)
On Mon, Sep 15, 2008 at 9:37 AM, Walter Bender <[EMAIL PROTECTED]> wrote: > I'd be nice to architect this in a way such that someone without > access to an XS could perhaps subscribe to an external service offered > up on the Internet to achieve the same functionality. We had (long > ago) a standing offer from Google at one point for such as service. That could be nice. I might be just as happy (or, happier?) with a system (admittedly similar to Apple's Time Machine) which would allow one to declare an external hard drive as a backup device, and then automatically handle backups to that drive whenever it is plugged in (just as we hope to have the XOs automatically backup to the school server). Anyone (I'm thinking G1G1) can get their hands on an external hard drive; there's much more overhead involved in a network backup in terms of accounts, agreements, bandwidth, etc. The benefit to the Google solution, of course, is that it might serve as a second tier for kids in schools as well. Essentially, those without a school server would just skip the intermediate step. - Eben > -walter > > On Sun, Sep 14, 2008 at 5:41 AM, Martin Langhoff > <[EMAIL PROTECTED]> wrote: >> On Sun, Sep 14, 2008 at 9:34 PM, Tomeu Vizoso <[EMAIL PROTECTED]> wrote: >>> these questions depend on the actual code that performs the restore. >>> I'm going to comment on what happens when the user clicks on an entry >>> from Browse (the only restore mechanism that is available today). >> >> Tomeu and I had a quick chat about this. A 'full restore' could be >> done from Journal via rsync+ssh with no changes on the XS side (at >> least for some scenarios). If we are going to do it for 9.1, we should >> be doing it now, not later... >> >> I am not sure how or when things will get prioritised for 9.1, but if >> 'full restore' is a high priority ticket (which I am not sure about) >> then we'd need to hear from Greg on this track, and have a bit of a >> catch up to flesh it out. >> >> For some cases the XS will need changes, so it might be a good idea to >> involve me as well (bear in mind I am in a tight release cycle right >> now though :-) so my time's a bit squeezed...) >> >> cheers, >> >> >> m >> -- >> [EMAIL PROTECTED] >> [EMAIL PROTECTED] -- School Server Architect >> - ask interesting questions >> - don't get distracted with shiny stuff - working code first >> - http://wiki.laptop.org/go/User:Martinlanghoff >> ___ >> Sugar mailing list >> [EMAIL PROTECTED] >> http://lists.laptop.org/listinfo/sugar >> > ___ > Sugar mailing list > [EMAIL PROTECTED] > http://lists.laptop.org/listinfo/sugar > ___ Server-devel mailing list [EMAIL PROTECTED] http://lists.laptop.org/listinfo/server-devel
Re: 8.2.0 Release Criteria & ECO Documentation (Michael Stone)
Hi, > We need to pick the set of activities which we will include in the > factory G1G1 image. > Can you add that to the check list so we are fully ready to produce > this image when its done? I should get my proposal in early, then. :) I'd like us to consider shipping the WikiBrowse English activity (available on the Activities page) with G1G1. - Chris. -- Chris Ball <[EMAIL PROTECTED]> ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: 8.2.0 Release Criteria & ECO Documentation (Michael Stone)
Hi Christoph, Not sure if the licensing thing will be a deal breaker for including activities in the manufactured image, but we should definitely get that right ASAP. All I'm saying is that we need to decide which activities to include in the image before they start manufacturing them for sale. I want to make sure that decision gets made early. We should also test those activities with an extra level of focus since we know they will get built in. Better to do that before the release is closed. That's why I think it merits a place on the ECO checklist. Thanks, Greg S Christoph Derndorfer wrote: > On Thu, Sep 11, 2008 at 11:40 PM, Greg Smith <[EMAIL PROTECTED]>wrote: > >> Hi Michael, >> >> I thought of one item we missed in making this checklist. >> >> We need to pick the set of activities which we will include in the >> factory G1G1 image. >> >> Can you add that to the check list so we are fully ready to produce this >> image when its done? > > > Don't the licensing issues with the activities that C. Scott brought up > yesterday have to be cleared before this list can be finalized? > > Or are you talking about a more abstract wishlist here? > > Regards, > Christoph > > >> If that decision can come out of synch with the blessing of the core >> image we can track it elsewhere. I just want to make sure we nail it >> down soon so we don't have a lot of latency between finalizing the image >> and getting it shipped on newly manufactured XOs. >> >> Thanks, >> >> Greg S >> >> *** >> >> Date: Wed, 10 Sep 2008 18:52:17 -0400 >> From: Michael Stone <[EMAIL PROTECTED]> >> Subject: 8.2.0 Release Criteria & ECO Documentation >> To: devel@lists.laptop.org >> Message-ID: <[EMAIL PROTECTED]> >> Content-Type: text/plain; charset=us-ascii; format=flowed >> >> In preparation for shipping an 8.2.0 build to manufacturing, we need to >> agree on release criteria. To that end, I have stubbed out rough ECO >> documentation for 8.2.0 at >> >>http://wiki.laptop.org/go/ECO/8.2.0 >>http://wiki.laptop.org/go/ECO/8.2.0/Checklist >> >> Please review these pages and offer suggestions on their talk pages so >> that I can fold your comments into the pages over the next week. >> >> So far, the most important changes I have made include: >> >>* Stating some of the technical documentation that future stable >> releases should include and making space for us to try creating that >> documentation for 8.2.0 at our leisure. >> >>* Stating the list of locales and keyboards which I believe must be >> minimally qualified for 8.2.0. See >> >>http://wiki.laptop.org/go/User:Mstone/Notes/Localization_1 >> >> for notes on what I mean by 'release X is qualified for locale Y'. >> >>* Created a test item for documentation signoff on the manual and >> activities signoff on the derivative builds. >> >>* Created final test items for release criteria including: >> >> "1 week of community testing" >> "all recent bugs triaged" >> "no 8.2.0 blockers" >> "release notes signoff" >> >> What have I missed? >> >> Michael >> ___ >> Devel mailing list >> Devel@lists.laptop.org >> http://lists.laptop.org/listinfo/devel >> > > > ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: 8.2.0 Release Criteria & ECO Documentation (Michael Stone)
On Thu, Sep 11, 2008 at 11:40 PM, Greg Smith <[EMAIL PROTECTED]>wrote: > Hi Michael, > > I thought of one item we missed in making this checklist. > > We need to pick the set of activities which we will include in the > factory G1G1 image. > > Can you add that to the check list so we are fully ready to produce this > image when its done? Don't the licensing issues with the activities that C. Scott brought up yesterday have to be cleared before this list can be finalized? Or are you talking about a more abstract wishlist here? Regards, Christoph > If that decision can come out of synch with the blessing of the core > image we can track it elsewhere. I just want to make sure we nail it > down soon so we don't have a lot of latency between finalizing the image > and getting it shipped on newly manufactured XOs. > > Thanks, > > Greg S > > *** > > Date: Wed, 10 Sep 2008 18:52:17 -0400 > From: Michael Stone <[EMAIL PROTECTED]> > Subject: 8.2.0 Release Criteria & ECO Documentation > To: devel@lists.laptop.org > Message-ID: <[EMAIL PROTECTED]> > Content-Type: text/plain; charset=us-ascii; format=flowed > > In preparation for shipping an 8.2.0 build to manufacturing, we need to > agree on release criteria. To that end, I have stubbed out rough ECO > documentation for 8.2.0 at > >http://wiki.laptop.org/go/ECO/8.2.0 >http://wiki.laptop.org/go/ECO/8.2.0/Checklist > > Please review these pages and offer suggestions on their talk pages so > that I can fold your comments into the pages over the next week. > > So far, the most important changes I have made include: > >* Stating some of the technical documentation that future stable > releases should include and making space for us to try creating that > documentation for 8.2.0 at our leisure. > >* Stating the list of locales and keyboards which I believe must be > minimally qualified for 8.2.0. See > > http://wiki.laptop.org/go/User:Mstone/Notes/Localization_1 > > for notes on what I mean by 'release X is qualified for locale Y'. > >* Created a test item for documentation signoff on the manual and > activities signoff on the derivative builds. > >* Created final test items for release criteria including: > > "1 week of community testing" > "all recent bugs triaged" > "no 8.2.0 blockers" > "release notes signoff" > > What have I missed? > > Michael > ___ > Devel mailing list > Devel@lists.laptop.org > http://lists.laptop.org/listinfo/devel > -- Christoph Derndorfer co-editor, olpcnews url: www.olpcnews.com e-mail: [EMAIL PROTECTED] ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
re: 8.2.0 Release Criteria & ECO Documentation (Michael Stone)
Hi Michael, I thought of one item we missed in making this checklist. We need to pick the set of activities which we will include in the factory G1G1 image. Can you add that to the check list so we are fully ready to produce this image when its done? If that decision can come out of synch with the blessing of the core image we can track it elsewhere. I just want to make sure we nail it down soon so we don't have a lot of latency between finalizing the image and getting it shipped on newly manufactured XOs. Thanks, Greg S *** Date: Wed, 10 Sep 2008 18:52:17 -0400 From: Michael Stone <[EMAIL PROTECTED]> Subject: 8.2.0 Release Criteria & ECO Documentation To: devel@lists.laptop.org Message-ID: <[EMAIL PROTECTED]> Content-Type: text/plain; charset=us-ascii; format=flowed In preparation for shipping an 8.2.0 build to manufacturing, we need to agree on release criteria. To that end, I have stubbed out rough ECO documentation for 8.2.0 at http://wiki.laptop.org/go/ECO/8.2.0 http://wiki.laptop.org/go/ECO/8.2.0/Checklist Please review these pages and offer suggestions on their talk pages so that I can fold your comments into the pages over the next week. So far, the most important changes I have made include: * Stating some of the technical documentation that future stable releases should include and making space for us to try creating that documentation for 8.2.0 at our leisure. * Stating the list of locales and keyboards which I believe must be minimally qualified for 8.2.0. See http://wiki.laptop.org/go/User:Mstone/Notes/Localization_1 for notes on what I mean by 'release X is qualified for locale Y'. * Created a test item for documentation signoff on the manual and activities signoff on the derivative builds. * Created final test items for release criteria including: "1 week of community testing" "all recent bugs triaged" "no 8.2.0 blockers" "release notes signoff" What have I missed? Michael ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
8.2.0 Release Criteria & ECO Documentation
In preparation for shipping an 8.2.0 build to manufacturing, we need to agree on release criteria. To that end, I have stubbed out rough ECO documentation for 8.2.0 at http://wiki.laptop.org/go/ECO/8.2.0 http://wiki.laptop.org/go/ECO/8.2.0/Checklist Please review these pages and offer suggestions on their talk pages so that I can fold your comments into the pages over the next week. So far, the most important changes I have made include: * Stating some of the technical documentation that future stable releases should include and making space for us to try creating that documentation for 8.2.0 at our leisure. * Stating the list of locales and keyboards which I believe must be minimally qualified for 8.2.0. See http://wiki.laptop.org/go/User:Mstone/Notes/Localization_1 for notes on what I mean by 'release X is qualified for locale Y'. * Created a test item for documentation signoff on the manual and activities signoff on the derivative builds. * Created final test items for release criteria including: "1 week of community testing" "all recent bugs triaged" "no 8.2.0 blockers" "release notes signoff" What have I missed? Michael ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
cerebro documentation
Hello world, The following document provides documentation on Cerebro's design, scalability properties, implementation and potential applications: http://cerebro.mit.edu/cerebro-final.pdf For the impatient, Chapter 3 provides a detailed technical and theoretical analysis of Cerebro's system architecture and design goals. Chapter 4 provides a description of Cerebro's implementation and its various modules. Chapter 5 provides an account of potential applications. This includes documentation on how the Xavier activity can be used for file-sharing, presence information, chat, etc. Chapter 6 evaluates Cerebro's performance by providing experimental results on a testbed with tens of nodes. With scalable regards, Pol -- Polychronis Ypodimatopoulos Graduate student Viral Communications MIT Media Lab Tel: +1 (617) 459-6058 http://www.mit.edu/~ypod/ ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Server-devel] Some documentation for DS-Backup
Hi Martin, That's a much requested feature from the field as you know! Thanks for working on it. Are you in synch with the XO side of the work needed? Can you check bug ID 7392 and confirm it covers what you need? When do you think we can release an XS image which supports this (be very conservative and no promises on date yet, just a swag for now). Bryan, If you're watching, can you read this spec and confirm it solves the problem from you perspective? If it does, its another reason to upgrade to 8.2.0 pending confirmation of the corresponding XS code... Thanks, Greg S > > -- > > Message: 2 > Date: Mon, 7 Jul 2008 20:45:08 -0300 > From: "Martin Langhoff" <[EMAIL PROTECTED]> > Subject: [Server-devel] Some documentation for DS-Backup > To: "XS Devel" <[EMAIL PROTECTED]> > Cc: OLPC Devel , [EMAIL PROTECTED], Greg Smith > <[EMAIL PROTECTED]> > Message-ID: > <[EMAIL PROTECTED]> > Content-Type: text/plain; charset=ISO-8859-1 > > (Sorry about the cross-post, this affects XS and XO...) > > Here is some initial documentation on DS-backup, including usage > scenarios, basic test steps, and longer-term plans > http://wiki.laptop.org/go/XS_Blueprints:Datastore_Simple_Backup_and_Restore > > cheers, > > > > m ___ Server-devel mailing list [EMAIL PROTECTED] http://lists.laptop.org/listinfo/server-devel
Some documentation for DS-Backup
(Sorry about the cross-post, this affects XS and XO...) Here is some initial documentation on DS-backup, including usage scenarios, basic test steps, and longer-term plans http://wiki.laptop.org/go/XS_Blueprints:Datastore_Simple_Backup_and_Restore cheers, m -- [EMAIL PROTECTED] [EMAIL PROTECTED] -- School Server Architect - ask interesting questions - don't get distracted with shiny stuff - working code first - http://wiki.laptop.org/go/User:Martinlanghoff ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Sugar API documentation
On 06.05.2008, at 11:14, Edward Cherlin wrote: > I often do what I call Defensive Documentation. I write the manual I > wanted to have in the first place. Nice term, "Defensive Documentation" :) That describes exactly why I made the "low-level" Sugar API documentation. It's not so much about the low level functions but rather about what is actually going on and required of an activity, independent of what language is being used. I wish I had had that kind of documentation when I started, because for me it's about understanding a system, not just using it. > Occasionally I can get paid to do this, although usually I get > decent source docs from engineers. Well, I'm just an engineer, and it shows in my style ;) Fortunately, Viewpoints Research pays me to work on the Sugar Etoys port, and they don't mind me doing occasional "peripheral" work, too. I did get help on IRC when I asked, although mostly I was just reverse-engineering the source code ... - Bert - ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Sugar API documentation
On Mon, May 5, 2008 at 1:40 PM, Bernie Innocenti <[EMAIL PROTECTED]> wrote: > Edward Cherlin wrote: ... > > I am a professional API tech writer, and I have been a developer. I > > would be delighted to work on this, if I could get the support I need. > > What do the developers use now? > > I talked about it with Marco on IRC. Some documentation is done with > gtk-doc because of our extensive use of the Gnome APIs. We are not > opposed to switch to something else (Doxygen, Epydoc) if there seems > to be benefits and someone volunteers to do the conversion. > > Checkout the main Sugar repository and have a look yourself: > git clone git://dev.laptop.org/sugar I'll have some questions tomorrow. > There are plenty of other related projects that could use some love. > > Personally, I think documenting these low-level details and the > internals of Sugar has a low effort/utility ratio. The code base > seemed sufficiently understandable even the first time I've looked > at it. There are some complaints. Perhaps we can find a low effort way to gain more utility. I'll take a look soon. > There's much more value in clearly describing the overall architecture, > the interaction between Sugar and Activities, the various DBus > protocols, etc. Some of this exists in wiki.latop.org, but much of > this information is incomplete, disorganized or just bitrotting. OK. I'll create an Architecture Doc page on the Wiki tomorrow, and put in an outline of the topics I know about. Pointers to other information will be needed. Let me know of anything you had a hard time discovering that still isn't in the Wiki, or is hard to find there. > So, rather than the API-oriented fine-grained documentation (which > may be a lot of to revise and extend), I'd like to see the stuff in > the wiki reorganized and revised to assume the form of a comprehensive, > top-down developer manual for the Sugar environment. Other wishes should be stated ASAP, because I am going to start designing a) what I am asked for b) what I see as needed I often do what I call Defensive Documentation. I write the manual I wanted to have in the first place. Occasionally I can get paid to do this, although usually I get decent source docs from engineers. > My non-pro $0.02 opinion. Edward, what do you think about it? I thought you would never ask. ^_^ > -- > \___/ > _| o | Bernie Innocenti - http://www.codewiz.org/ > \|_X_| "It's an education project, not a laptop project!" > -- Edward Cherlin End Poverty at a Profit by teaching children business http://www.EarthTreasury.org/ "The best way to predict the future is to invent it."--Alan Kay ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Documentation & Sign-offs for Update.1 RC3 (update.1-703)
Folks, First, thanks are due to everyone who has helped close U.1 bugs in the past few days and special thanks are due to everyone who has assisted in testing update.1 builds 702 and 703. Next: in order to release update.1-703 as Update.1 RC3, we need to complete some approximation of the "software engineering change order" documentation at http://wiki.laptop.org/go/OLPC_SW-ECO_4 and http://wiki.laptop.org/go/OLPC_SW-ECO_4_Checklist In the absence of an official QA lead, I will sign for the items about which I have positive knowledge. For the time being, I will leave any remaining items blank. - Dennis, please complete the "build engineer" sections. - Richard, please sign off on Q2D14 and please send me the GPG key you used to sign it so that I can verify the published signature. Thanks very much, Michael P.S. - Food for thought: Bugs tagged "release?": http://tinyurl.com/2zpth4 Bugs tagged "relnote?": http://tinyurl.com/26rwl7 Stale bugs tagged "release?": http://dev.laptop.org/report/17?TIME=267300 Fresh bugs tagged "release?": http://dev.laptop.org/report/16?TIME=267300 ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
On Jan 1, 2008 3:14 PM, M. Edward (Ed) Borasky <[EMAIL PROTECTED]> wrote: > Edward Cherlin wrote: > > Does anybody know of a documentation tool for Open Firmware, or for > > FORTH more generally? Exploring using 'words' and 'see' > > Are you looking for automated documentation generation, or FORTH coding > and documentation standards? I don't know about the former, but there is > a well-established set of the latter, and given adherence, I'm sure the > former is eminently possible. > > "The FORTH community" is fairly small (relative to, say, Python), and as > a result, most FORTH programmers don't have much trouble reading the > code of other FORTH programmers. Reading FORTH code is easy. Knowing which code to read requires experience. > But I don't know about outsiders coming > to FORTH from "more traditional" languages. :) Or no language. The children, in particular. I have long been of the opinion that you don't understand computing unless you have some grasp of hardware, and also of languages with quite different models of computation. At least LISP (well, Scheme or Logo), FORTH, Smalltalk, APL, and more conventional languages. Python definitely; C, C++, Java, only later when you won't mistake their design flaws and political compromises for received wisdom. Basically, languages that follow the dictum that Einstein apparently didn't say, but everybody thinks he should have: Everything should be made as simple as possible, but no simpler. We are in a good situation on the XO, and it's going to get better. -- Edward Cherlin Earth Treasury: End Poverty at a Profit http://www.EarthTreasury.org/ "The best way to predict the future is to invent it."--Alan Kay ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
First, thanks to everybody who replied to my requests on Python, Smalltalk, and FORTH documentation tools. I will put the links you have given me into the document outlines linked from the OLPC Publications page, and at some point we can start expanding the outlines into draft documents. Further comments on these Wiki pages will be greatly appreciated. On Jan 1, 2008 3:50 PM, Mitch Bradley <[EMAIL PROTECTED]> wrote: > Edward Cherlin wrote: > > > >> Does anybody know of a documentation tool for Open Firmware, or for > >> FORTH more generally? Exploring using 'words' and 'see' > >> > > > > is fun up to a point if you're learning FORTH, but really doesn't cut > > it for supporting documentation. > > > > > I presume that you have seen the tutorials at > > http://wiki.laptop.org/go/Forth_Lessons Yes. And I programmed in FORTH many years ago. > The basic Open Firmware level is reasonably well documented - > > http://docs.sun.com/app/docs/doc/805-4436 > http://firmworks.com/QuickRef.html That's what I mean. Thanks. > The OLPC-specific stuff could certainly use some additional > documentation. The source code for the OLPC-specific stuff has some > amount of internal documentation that could be extracted. Each source > file has a "purpose" comment at the top of the file, and many of the > individual word definitions are preceded by a brief description. For > example, the file cpu/x86/pc/olpc.fth begins with: > > purpose: Determine the board revision based on hardware and EC info > > and that file defines the word "model-name$" as follows: > > \ Constructs a string like "B4" or "preB4" or "postB4" > : model-name$ ( -- model$ ) > > Many, but certainly not all, of the words that can plausibly be used > interactively have brief description strings like that. > > Some words don't have brief descriptions in the source, and probably > never will have them, based on the clarity of their names . For > example, for the word "bios-checksum-bad? ( -- flag )", I didn't feel > compelled to write "\ Returns true if the BIOS checksum is bad". The > various "xxx@" and "xxx!" words fall into that category, once you know > the general pattern of "@" and "!". But even so, it would be nice to > have a compendium of those words with English descriptions for easy > reference. Exactly. It should be fairly easy to do. > I'm not a big fan of automated documentation tools. They can help with > the mechanics of extracting documentation strings from source code, but > in my experience, such documentation is only marginally useful. The > really hard part of understanding how something works is the contextual > stuff - the circumstances under which it is appropriate to call a given > function, how it fits together with related stuff, etc. Exactly. I have been working as an API Tech Writer for most of the last decade. Getting decent sample code out of developers has always been the hardest part of the job, and frequently I just had to write it myself. > Phrases are > more enlightening than individual words. Automated documentation > extraction tends to describe individual trees, leaving you wondering > about the overall shape of the forest. Projects that are set up for > auto doc tools tend to have long structured comment blocks before every > function. The individual fields are often extremely boring - like > "Outputs: none", and the overall size of the comment block takes up so > much screen real estate that the actual code is lost among the boilerplate. > > Going back to the "bios-checksum-bad? ( -- flag )" example, the usual > tendency would be to say something obviously correct, and entirely > pointless, like "Returns a boolean flag that is true if the BIOS > checksum is bad". What really should be said is something like: > > Conventional PC BIOSes checksum the CMOS RAM between indices 0x10 and > 0x2d inclusive, storing the arithmetic sum as a 2-byte big-endian > integer at indices 0x2e and 0x2f. "bios-checksum-bad?" tests that > checksum. It is an implementation factor of "init-bios-cmos", which > ensures that said checksum is correct, fixing the checksum by zeroing > that entire area if not. > > But of course people rarely write documentation that complete, for any > number of reasons. Are you putting your hand up? > That said, I really need to go through all the new OLPC code and at > least add brief descriptions for all the top-level words. Ah. Evidently Yes. Thanks. > Meanwhile, if anyone wants to look at the source cod
Re: Updates API documentation for everything.
Edward Cherlin wrote: > >> Does anybody know of a documentation tool for Open Firmware, or for >> FORTH more generally? Exploring using 'words' and 'see' >> > > is fun up to a point if you're learning FORTH, but really doesn't cut > it for supporting documentation. > I presume that you have seen the tutorials at http://wiki.laptop.org/go/Forth_Lessons The basic Open Firmware level is reasonably well documented - http://docs.sun.com/app/docs/doc/805-4436 http://firmworks.com/QuickRef.html The OLPC-specific stuff could certainly use some additional documentation. The source code for the OLPC-specific stuff has some amount of internal documentation that could be extracted. Each source file has a "purpose" comment at the top of the file, and many of the individual word definitions are preceded by a brief description. For example, the file cpu/x86/pc/olpc.fth begins with: purpose: Determine the board revision based on hardware and EC info and that file defines the word "model-name$" as follows: \ Constructs a string like "B4" or "preB4" or "postB4" : model-name$ ( -- model$ ) Many, but certainly not all, of the words that can plausibly be used interactively have brief description strings like that. Some words don't have brief descriptions in the source, and probably never will have them, based on the clarity of their names . For example, for the word "bios-checksum-bad? ( -- flag )", I didn't feel compelled to write "\ Returns true if the BIOS checksum is bad". The various "xxx@" and "xxx!" words fall into that category, once you know the general pattern of "@" and "!". But even so, it would be nice to have a compendium of those words with English descriptions for easy reference. I'm not a big fan of automated documentation tools. They can help with the mechanics of extracting documentation strings from source code, but in my experience, such documentation is only marginally useful. The really hard part of understanding how something works is the contextual stuff - the circumstances under which it is appropriate to call a given function, how it fits together with related stuff, etc. Phrases are more enlightening than individual words. Automated documentation extraction tends to describe individual trees, leaving you wondering about the overall shape of the forest. Projects that are set up for auto doc tools tend to have long structured comment blocks before every function. The individual fields are often extremely boring - like "Outputs: none", and the overall size of the comment block takes up so much screen real estate that the actual code is lost among the boilerplate. Going back to the "bios-checksum-bad? ( -- flag )" example, the usual tendency would be to say something obviously correct, and entirely pointless, like "Returns a boolean flag that is true if the BIOS checksum is bad". What really should be said is something like: Conventional PC BIOSes checksum the CMOS RAM between indices 0x10 and 0x2d inclusive, storing the arithmetic sum as a 2-byte big-endian integer at indices 0x2e and 0x2f. "bios-checksum-bad?" tests that checksum. It is an implementation factor of "init-bios-cmos", which ensures that said checksum is correct, fixing the checksum by zeroing that entire area if not. But of course people rarely write documentation that complete, for any number of reasons. That said, I really need to go through all the new OLPC code and at least add brief descriptions for all the top-level words. Meanwhile, if anyone wants to look at the source code, the OLPC-specific bits are mostly collected in a few directories, primarily cpu/x86/build/olpc/ and dev/olpc/* The source tree is at http://openbios.org/Open_Firmware ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
From: Edward Cherlin <[EMAIL PROTECTED]> >And what about Smalltalk/Etoys? Not sure what level of doc you're seeking. If I misunderstood you, I apologize. Smalltalk's libraries are to a certain extent self-documenting in its browser, which is good because they vary depending on whatever you've synced from the central repositories. For Squeak overall, we have http://www.squeakbyexample.org. For how-to Etoys (the media/animation layer), I'm pretty impressed so far by the series of videos on http://www.waveplace.com/movies/ (speaking as somebody who doesn't care for non-written doc as a rule). ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
Edward Cherlin wrote: > Does anybody know of a documentation tool for Open Firmware, or for > FORTH more generally? Exploring using 'words' and 'see' Are you looking for automated documentation generation, or FORTH coding and documentation standards? I don't know about the former, but there is a well-established set of the latter, and given adherence, I'm sure the former is eminently possible. "The FORTH community" is fairly small (relative to, say, Python), and as a result, most FORTH programmers don't have much trouble reading the code of other FORTH programmers. But I don't know about outsiders coming to FORTH from "more traditional" languages. :) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
Sorry. It got away from me. On Jan 1, 2008 2:11 PM, Edward Cherlin <[EMAIL PROTECTED]> wrote: > On Dec 30, 2007 10:20 AM, C. Scott Ananian <[EMAIL PROTECTED]> wrote: > > I have run the python documentation tool 'epydoc' on the contents of > > the joyride-1477 release. The results are here: > >http://dev.laptop.org/~cscott/joyride-1477-api/ > > Thanks. I was wishing for that. Can you do the other major builds > also? I am running 653, and I keep hearing about Update.1. > > Does anybody know of a documentation tool for Open Firmware, or for > FORTH more generally? Exploring using 'words' and 'see' is fun up to a point if you're learning FORTH, but really doesn't cut it for supporting documentation. And what about Smalltalk/Etoys? > > This is probably the most up-to-date documentation available now for > > Sugar, the update and contents tools, rainbow, etc. > > I plan to integrate this into the joyride build process, so that there > > are always current API docs available. > > Thank you, thank you. When you can create a URL that will always go to > the latest version, please add it to the Wiki. > > > Comments welcome! And those of you who have not adequately documented > > your code, please do. Module-level comments in particular are very > > helpful, and often missing. > > --scott > > > > -- > > ( http://cscott.net/ ) > > ___ > > Devel mailing list > > Devel@lists.laptop.org > > http://lists.laptop.org/listinfo/devel > > http://www.documentia.ca/lies.htm > Biggest Lies Heard by Technical Writers > * You should have a fully-functional product in your hands in plenty > of time to complete your document. > * The product's so intuitive, it practically writes the manual itself. > * You won't be thought of as a nuisance by the SME's. They accept that > you're a peer and respect that you have a job to do. > * I'd make that more abstract. We'll make sure you have everything you > need to get the job done. > * As the tech writer at our company, you will have full, unrestricted > access to the devolopment team's time and resources. > etc. > -- > Edward Cherlin > Earth Treasury: End Poverty at a Profit > http://www.EarthTreasury.org/ > "The best way to predict the future is to invent it."--Alan Kay > -- Edward Cherlin Earth Treasury: End Poverty at a Profit http://www.EarthTreasury.org/ "The best way to predict the future is to invent it."--Alan Kay ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
On Dec 30, 2007 10:20 AM, C. Scott Ananian <[EMAIL PROTECTED]> wrote: > I have run the python documentation tool 'epydoc' on the contents of > the joyride-1477 release. The results are here: >http://dev.laptop.org/~cscott/joyride-1477-api/ Thanks. I was wishing for that. Can you do the other major builds also? I am running 653, and I keep hearing about Update.1. Does anybody know of a documentation tool for Open Firmware, or for FORTH more generally? Exploring using 'words' and 'see' > This is probably the most up-to-date documentation available now for > Sugar, the update and contents tools, rainbow, etc. > I plan to integrate this into the joyride build process, so that there > are always current API docs available. Thank you, thank you. When you can create a URL that will always go to the latest version, please add it to the Wiki. > Comments welcome! And those of you who have not adequately documented > your code, please do. Module-level comments in particular are very > helpful, and often missing. > --scott > > -- > ( http://cscott.net/ ) > ___ > Devel mailing list > Devel@lists.laptop.org > http://lists.laptop.org/listinfo/devel http://www.documentia.ca/lies.htm Biggest Lies Heard by Technical Writers * You should have a fully-functional product in your hands in plenty of time to complete your document. * The product's so intuitive, it practically writes the manual itself. * You won't be thought of as a nuisance by the SME's. They accept that you're a peer and respect that you have a job to do. * I'd make that more abstract. We'll make sure you have everything you need to get the job done. * As the tech writer at our company, you will have full, unrestricted access to the devolopment team's time and resources. etc. -- Edward Cherlin Earth Treasury: End Poverty at a Profit http://www.EarthTreasury.org/ "The best way to predict the future is to invent it."--Alan Kay ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updated API documentation for everything.
C. Scott Ananian wrote: > The subject line of my previous message should have been 'updated API > documentation', not 'updates API documentation', sigh. > --scott > > Scott, Is this going to be a more or less permanent location? I am setting my link on my PlayGo activity page to the http://dev.laptop.org/~cscott/joyride-1477-api/sugar.activity-module.html. Do you plan to move this into the wiki? -Gerard ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
I should have also noted that epydoc is configured to use ReStructuredText by default for docstrings (http://docutils.sourceforge.net/rst.html) -- if you prefer to use a different markup language set the global __docformat__ at the top level of your module, as described here: http://epydoc.sourceforge.net/manual-othermarkup.html It is my understanding that ReStructuredText will be the recommended markup format for Python2.6; it also has the benefit of being remarkably readable in plain text. --scott -- ( http://cscott.net/ ) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
On Dec 30, 2007 1:31 PM, Jeffrey Kesselman <[EMAIL PROTECTED]> wrote: > In general it would be good if a docs could be made downloadable... I > don't always have net access. Good point. When I integrate this into the build process, I'll be sure to .zip up the files as well. In the interim: http://dev.laptop.org/~cscott/joyride-1477-api.zip --scott -- ( http://cscott.net/ ) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Updates API documentation for everything.
In general it would be good if a docs could be made downloadable... I don't always have net access. On Dec 30, 2007 1:20 PM, C. Scott Ananian <[EMAIL PROTECTED]> wrote: > I have run the python documentation tool 'epydoc' on the contents of > the joyride-1477 release. The results are here: >http://dev.laptop.org/~cscott/joyride-1477-api/ > This is probably the most up-to-date documentation available now for > Sugar, the update and contents tools, rainbow, etc. > I plan to integrate this into the joyride build process, so that there > are always current API docs available. > > Comments welcome! And those of you who have not adequately documented > your code, please do. Module-level comments in particular are very > helpful, and often missing. > --scott > > -- > ( http://cscott.net/ ) > ___ > Devel mailing list > Devel@lists.laptop.org > http://lists.laptop.org/listinfo/devel > -- ~~ Microsoft help desk says: reply hazy, ask again later. ~~ ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Updated API documentation for everything.
The subject line of my previous message should have been 'updated API documentation', not 'updates API documentation', sigh. --scott -- ( http://cscott.net/ ) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Updates API documentation for everything.
I have run the python documentation tool 'epydoc' on the contents of the joyride-1477 release. The results are here: http://dev.laptop.org/~cscott/joyride-1477-api/ This is probably the most up-to-date documentation available now for Sugar, the update and contents tools, rainbow, etc. I plan to integrate this into the joyride build process, so that there are always current API docs available. Comments welcome! And those of you who have not adequately documented your code, please do. Module-level comments in particular are very helpful, and often missing. --scott -- ( http://cscott.net/ ) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: slightly long and detailed proposal for documentation-translation workflow
On 10/15/07, Ed Trager <[EMAIL PROTECTED]> wrote: > > translate and easier for younger readers to understand. This will also > > help the writer avoid the passive construction, which is very > > difficult for some non-native English speakers to understand. > > I agree completely that the English passive construction should be > avoided at all times. You mean: "I agree completely that *one* should avoid the English passive construction at all times." Don't you? --scott -- ( http://cscott.net/ ) ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: slightly long and detailed proposal for documentation-translation workflow
Ah, the manuals are needed to keep teachers and parents in their "comfort zone". That the children will teach each other we have no doubt at all, but older people have different expectations. And keeping them comfortable with OLPC is also needed. Also remember that the collaboration aspects are new, and not what people have seen before. I would expect that there is where we should concentrate our effort most. - Jim On Mon, 2007-10-15 at 17:09 -0700, Steve Fullerton wrote: > Hi Ed and all, > > I fully appreciate the detail. However, IMHO I think that there is > some re-thinking required re: the traditional "user" documentation. > The core of the OLPC (literally one laptop per child; the model does > not work as well if there is not possession of a laptop for each > child) is that of collaboration. > > One child learning something and then teaching his/her classmates. > OLPC machines are not meant to be used in isolation. You could > actually make a credible argument that user manuals are bad for the > project. > > The highly intuitive design of Sugar and the experience of the pilots > bears this out. The children seem to do just great without manuals, > discovery is enhanced, and many of the constructionist ideals are > realized. > > What do you think? > > On 10/15/07, Ed Trager <[EMAIL PROTECTED]> wrote: > Hi, Michael, > > Just a few comments for consideration by everyone: > > > ... > > Doc writing conventions: > > > > Some linguistic research has been done on "simplified > English" as a > > subset of English to use for low-level learners, and I think > that it > > might be a good place to look for ways to simplify the > source_docs. > > But just thinking intuitively, I have cooked up the > following > > suggestions in order to generate discussion: > > > > * Pronouns. > > o Use the first-person singular pronoun "I" to > represent the > > author of the docs, > > o the second-person singular pronoun "you" to > represent the > > reader of the docs, and > > o the first-person plural pronoun "we" to > represent the OLPC project. > > > > o Examples. "We have designed a screen that > switches to > > black-and-white to conserve energy. I will explain how to > switch your > > screen to black-and-white. First, you press the X button on > your > > keyboard" Because we want the docs to be easily > translated and > > easily understood, the tone should be personal, using "I" > for the > > voice of the writer. This will be easier for amateur > translators to > > translate and easier for younger readers to understand. This > will also > > help the writer avoid the passive construction, which is > very > > difficult for some non-native English speakers to > understand. > > I agree completely that the English passive construction > should be > avoided at all times. > > I mostly agree with your suggestion on use of pronouns. Use > of "I" > and "we" are fine. > > REGARDING THE PRONOUN "YOU" IN ENGLISH: > -- > > However, as a native English speaker, I find the use of the > pronoun > "you" in the imperative mood often quite jarring. > > Imperative sentences in which the "you" is absent are > understood by > native speakers of English to convey a softer, less imperative > tone. > Such sentences are considered more polite. Compare: > > (A) "First you press the X button on the keyboard." > > ... versus: > > (B) "First, press the X button on the keyboard." > > One or two instances of "you" in imperatives or directions in > spoken > or written English may not seem too bad, but after a series of > them, > it becomes irritating. > > So while I have no objection to simple English which will be >
Re: slightly long and detailed proposal for documentation-translation workflow
fyi val scarlata and i went back through material to try and make something more user friendly. she scanned through wiki and assembled various links as good cop, then I played bad cop to try and control scope, she had a documentation party with a couple of students to assemble material -- and now three tech writers who have volunteered are working very much on trying to make it user friendly (and extensible to incorporate software flux, and adaptable into various languages). There is a proto google doc that anyone who is interested is welcome to view, join in, or if you email me i'll send a pdf. haven't had time to situate in wiki yet. I saw marklogic do very nice work with x-query allowing people to self-assemble their own books on the fly. i think this is how safari u. does things. kind of like alacarte ebooks. it would be cool if flowr foundation (open source x-query) could help put something like that together. but that would be porsche -- it would be nice just to have a scalable system period -- and that's what we're working on. On 10/16/07, Polychronis Ypodimatopoulos <[EMAIL PROTECTED]> wrote: > > heh, I totally agree, but this doesn't mean that there isn't a market > for a book like that (unfortunately!). > > Apart from the fact that some people feel "disabled" without a book, > there still is *not* a "user-friendly" introduction on how to use the > laptop (let alone how it works) and I doubt that there will be one > anytime soon because OLPC's primary mission is not to sell the XO in the > US market. However, I'm afraid that OLPC will have to deal with > user support! I hate to say this but there were already a couple of > people visiting the lab, asking about where to buy the laptops and > whether they're good for their needs. > > Pol > > Mitch Bradley wrote: > > At the current rate of XO software churn, any printed book will be > > obsolete/inaccurate before the ink is dry. > > > > Todd Kelsey wrote: > > > >> I have been struggling with my literary agent and trying to knock > >> someone over the head with a wet noodle into realizing that there > >> *will* be a market for a book, and trying to suggest going with an > >> e-book, with editorial support from a publisher, put it on amazon, > >> develop the whole thing in a robust authoring cms so updates and > >> multilingual versions can be easily made. one publisher responded with > >> fear, blah blah blah, and I made an attempt to provide rationales > >> (including insights from Wikinomics, which has helped me to be able to > >> articulate some of the value propositions), but I'm 2 degrees away > >> from throwing in the towel, and inviting whoever wants to join me in > >> making a multimodal community book. then maybe when the publishers > >> wake up they could license it and use their distribution channels to > >> put it in stores. > >> > >> I don't know if the publishers realize how cool the little green xo is > >> as a way for people to get acquainted with Linux. > >> > >> Ok I'm throwing in the towel. We could call it the Hitchhiker's Guide > >> to the Laptop. I don't care what the title is. The community could > >> name it, write it. If anyone is interested in helping learners who > >> desire a book to get acquainted with the very wonderful work you are > >> doing, please feel free to get in touch. > >> > >> Maybe the proceeds from the book could go towards a series of laptop > >> libraries where the laptops could be checked out by kids. > >> > >> I guess in the same time it took to write this email I could have > >> written a wiki page. > >> > >> On 10/16/07, *Steve Fullerton* <[EMAIL PROTECTED] > >> <mailto:[EMAIL PROTECTED]>> wrote: > >> > >> Good points. The OLPC is designed around collaboration. The > >> model really works well where every child in a class has his/her > >> own laptop, uses it in and out of school, and lives in close > >> enough proximity to other class members to make the Mesh work. In > >> class one kid discovers how to do something and teaches the other > >> kids (and teachers as well). > >> > >> In an address at Harvard Law, Negroponte said something like: > >> "People ask me who is going to teach the teachers to teach the > >> children how to use the XOs --- and I wonder what planet are they > >> on? ..." > >> > >> A child who gets one through G1G1 in isolation will
Re: slightly long and detailed proposal for documentation-translation workflow
heh, I totally agree, but this doesn't mean that there isn't a market for a book like that (unfortunately!). Apart from the fact that some people feel "disabled" without a book, there still is *not* a "user-friendly" introduction on how to use the laptop (let alone how it works) and I doubt that there will be one anytime soon because OLPC's primary mission is not to sell the XO in the US market. However, I'm afraid that OLPC will have to deal with user support! I hate to say this but there were already a couple of people visiting the lab, asking about where to buy the laptops and whether they're good for their needs. Pol Mitch Bradley wrote: > At the current rate of XO software churn, any printed book will be > obsolete/inaccurate before the ink is dry. > > Todd Kelsey wrote: > >> I have been struggling with my literary agent and trying to knock >> someone over the head with a wet noodle into realizing that there >> *will* be a market for a book, and trying to suggest going with an >> e-book, with editorial support from a publisher, put it on amazon, >> develop the whole thing in a robust authoring cms so updates and >> multilingual versions can be easily made. one publisher responded with >> fear, blah blah blah, and I made an attempt to provide rationales >> (including insights from Wikinomics, which has helped me to be able to >> articulate some of the value propositions), but I'm 2 degrees away >> from throwing in the towel, and inviting whoever wants to join me in >> making a multimodal community book. then maybe when the publishers >> wake up they could license it and use their distribution channels to >> put it in stores. >> >> I don't know if the publishers realize how cool the little green xo is >> as a way for people to get acquainted with Linux. >> >> Ok I'm throwing in the towel. We could call it the Hitchhiker's Guide >> to the Laptop. I don't care what the title is. The community could >> name it, write it. If anyone is interested in helping learners who >> desire a book to get acquainted with the very wonderful work you are >> doing, please feel free to get in touch. >> >> Maybe the proceeds from the book could go towards a series of laptop >> libraries where the laptops could be checked out by kids. >> >> I guess in the same time it took to write this email I could have >> written a wiki page. >> >> On 10/16/07, *Steve Fullerton* <[EMAIL PROTECTED] >> <mailto:[EMAIL PROTECTED]>> wrote: >> >> Good points. The OLPC is designed around collaboration. The >> model really works well where every child in a class has his/her >> own laptop, uses it in and out of school, and lives in close >> enough proximity to other class members to make the Mesh work. In >> class one kid discovers how to do something and teaches the other >> kids (and teachers as well). >> >> In an address at Harvard Law, Negroponte said something like: >> "People ask me who is going to teach the teachers to teach the >> children how to use the XOs --- and I wonder what planet are they >> on? ..." >> >> A child who gets one through G1G1 in isolation will not be able to >> fully benefit from collaboration and thus, along with >> parent/tutor, would definately benefit from user documentation in >> lieu of help from others in class. Likewise, the Carlos Slims >> approach of putting them in Mexican libraries. >> >> If G1G1 goes big-time in November, you can sure bet that there >> will be "OLPC for Dummies" books, etc. by Christmas. >> >> On 10/15/07, *Todd Kelsey * <[EMAIL PROTECTED] >> <mailto:[EMAIL PROTECTED]>> wrote: >> >> I am amazed and inspired by all the wonderful projects and >> activities that have arisen from the laptop project -- and >> though I was skeptical at first, I have also come to >> appreciate the constructivist approach to education; I didn't >> "get it" until I came to appreciate the notion of allowing >> children to come to "aha" moments on their own. The fact that >> children do fine without manuals at the present level of >> interaction is a testament to the design of the computer and >> the philosophy behind it. As generation xo grows older, I >> think they will want to get deeper into the systems, and as >> they do, I think they will want more informat
Re: slightly long and detailed proposal for documentation-translation workflow
At the current rate of XO software churn, any printed book will be obsolete/inaccurate before the ink is dry. Todd Kelsey wrote: > I have been struggling with my literary agent and trying to knock > someone over the head with a wet noodle into realizing that there > *will* be a market for a book, and trying to suggest going with an > e-book, with editorial support from a publisher, put it on amazon, > develop the whole thing in a robust authoring cms so updates and > multilingual versions can be easily made. one publisher responded with > fear, blah blah blah, and I made an attempt to provide rationales > (including insights from Wikinomics, which has helped me to be able to > articulate some of the value propositions), but I'm 2 degrees away > from throwing in the towel, and inviting whoever wants to join me in > making a multimodal community book. then maybe when the publishers > wake up they could license it and use their distribution channels to > put it in stores. > > I don't know if the publishers realize how cool the little green xo is > as a way for people to get acquainted with Linux. > > Ok I'm throwing in the towel. We could call it the Hitchhiker's Guide > to the Laptop. I don't care what the title is. The community could > name it, write it. If anyone is interested in helping learners who > desire a book to get acquainted with the very wonderful work you are > doing, please feel free to get in touch. > > Maybe the proceeds from the book could go towards a series of laptop > libraries where the laptops could be checked out by kids. > > I guess in the same time it took to write this email I could have > written a wiki page. > > On 10/16/07, *Steve Fullerton* <[EMAIL PROTECTED] > <mailto:[EMAIL PROTECTED]>> wrote: > > Good points. The OLPC is designed around collaboration. The > model really works well where every child in a class has his/her > own laptop, uses it in and out of school, and lives in close > enough proximity to other class members to make the Mesh work. In > class one kid discovers how to do something and teaches the other > kids (and teachers as well). > > In an address at Harvard Law, Negroponte said something like: > "People ask me who is going to teach the teachers to teach the > children how to use the XOs --- and I wonder what planet are they > on? ..." > > A child who gets one through G1G1 in isolation will not be able to > fully benefit from collaboration and thus, along with > parent/tutor, would definately benefit from user documentation in > lieu of help from others in class. Likewise, the Carlos Slims > approach of putting them in Mexican libraries. > > If G1G1 goes big-time in November, you can sure bet that there > will be "OLPC for Dummies" books, etc. by Christmas. > > On 10/15/07, *Todd Kelsey * <[EMAIL PROTECTED] > <mailto:[EMAIL PROTECTED]>> wrote: > > I am amazed and inspired by all the wonderful projects and > activities that have arisen from the laptop project -- and > though I was skeptical at first, I have also come to > appreciate the constructivist approach to education; I didn't > "get it" until I came to appreciate the notion of allowing > children to come to "aha" moments on their own. The fact that > children do fine without manuals at the present level of > interaction is a testament to the design of the computer and > the philosophy behind it. As generation xo grows older, I > think they will want to get deeper into the systems, and as > they do, I think they will want more information, and I'd like > to help make that freely available. > > I think a user manual or documentation will be more helpful > for adult learners who will end up participating in the laptop > community, and who would find it helpful to have something to > refer to. Perhaps users could learn many things simply by > exploring, and yet they might appreciate having something to > turn to. Other people may not have personal possession of a > laptop, but would be interested in learning how they could > support the project. Some people who order the laptops through > www.xogiving.org <http://www.xogiving.org> will get frustrated > with the laptop if they have no resources to turn to, and I'd > like to help them have fun. > > I think the idea of encouraging children to help each other > learn is wonderful; I also appreciate the prin
Re: slightly long and detailed proposal for documentation-translation workflow
I have been struggling with my literary agent and trying to knock someone over the head with a wet noodle into realizing that there *will* be a market for a book, and trying to suggest going with an e-book, with editorial support from a publisher, put it on amazon, develop the whole thing in a robust authoring cms so updates and multilingual versions can be easily made. one publisher responded with fear, blah blah blah, and I made an attempt to provide rationales (including insights from Wikinomics, which has helped me to be able to articulate some of the value propositions), but I'm 2 degrees away from throwing in the towel, and inviting whoever wants to join me in making a multimodal community book. then maybe when the publishers wake up they could license it and use their distribution channels to put it in stores. I don't know if the publishers realize how cool the little green xo is as a way for people to get acquainted with Linux. Ok I'm throwing in the towel. We could call it the Hitchhiker's Guide to the Laptop. I don't care what the title is. The community could name it, write it. If anyone is interested in helping learners who desire a book to get acquainted with the very wonderful work you are doing, please feel free to get in touch. Maybe the proceeds from the book could go towards a series of laptop libraries where the laptops could be checked out by kids. I guess in the same time it took to write this email I could have written a wiki page. On 10/16/07, Steve Fullerton <[EMAIL PROTECTED]> wrote: > > Good points. The OLPC is designed around collaboration. The model really > works well where every child in a class has his/her own laptop, uses it in > and out of school, and lives in close enough proximity to other class > members to make the Mesh work. In class one kid discovers how to do > something and teaches the other kids (and teachers as well). > > In an address at Harvard Law, Negroponte said something like: "People ask > me who is going to teach the teachers to teach the children how to use the > XOs --- and I wonder what planet are they on? ..." > > A child who gets one through G1G1 in isolation will not be able to fully > benefit from collaboration and thus, along with parent/tutor, would > definately benefit from user documentation in lieu of help from others in > class. Likewise, the Carlos Slims approach of putting them in Mexican > libraries. > > If G1G1 goes big-time in November, you can sure bet that there will be > "OLPC for Dummies" books, etc. by Christmas. > > On 10/15/07, Todd Kelsey <[EMAIL PROTECTED]> wrote: > > > > I am amazed and inspired by all the wonderful projects and activities > > that have arisen from the laptop project -- and though I was skeptical at > > first, I have also come to appreciate the constructivist approach to > > education; I didn't "get it" until I came to appreciate the notion of > > allowing children to come to "aha" moments on their own. The fact that > > children do fine without manuals at the present level of interaction is a > > testament to the design of the computer and the philosophy behind it. As > > generation xo grows older, I think they will want to get deeper into the > > systems, and as they do, I think they will want more information, and I'd > > like to help make that freely available. > > > > I think a user manual or documentation will be more helpful for adult > > learners who will end up participating in the laptop community, and who > > would find it helpful to have something to refer to. Perhaps users could > > learn many things simply by exploring, and yet they might appreciate having > > something to turn to. Other people may not have personal possession of a > > laptop, but would be interested in learning how they could support the > > project. Some people who order the laptops through www.xogiving.org will > > get frustrated with the laptop if they have no resources to turn to, and I'd > > like to help them have fun. > > > > I think the idea of encouraging children to help each other learn is > > wonderful; I also appreciate the principle of inclusiveness, and I think > > that one way to be inclusive is to address various learning styles. > > > > On 10/15/07, Steve Fullerton < [EMAIL PROTECTED]> wrote: > > > > > > Hi Ed and all, > > > > > > I fully appreciate the detail. However, IMHO I think that there is > > > some re-thinking required re: the traditional "user" documentation. The > > > core of the OLPC (literally one laptop per child; the model does not work > > > as well if there is not possession of a laptop for ea
Re: slightly long and detailed proposal for documentation-translation workflow
Good points. The OLPC is designed around collaboration. The model really works well where every child in a class has his/her own laptop, uses it in and out of school, and lives in close enough proximity to other class members to make the Mesh work. In class one kid discovers how to do something and teaches the other kids (and teachers as well). In an address at Harvard Law, Negroponte said something like: "People ask me who is going to teach the teachers to teach the children how to use the XOs --- and I wonder what planet are they on? ..." A child who gets one through G1G1 in isolation will not be able to fully benefit from collaboration and thus, along with parent/tutor, would definately benefit from user documentation in lieu of help from others in class. Likewise, the Carlos Slims approach of putting them in Mexican libraries. If G1G1 goes big-time in November, you can sure bet that there will be "OLPC for Dummies" books, etc. by Christmas. On 10/15/07, Todd Kelsey <[EMAIL PROTECTED]> wrote: > > I am amazed and inspired by all the wonderful projects and activities that > have arisen from the laptop project -- and though I was skeptical at first, > I have also come to appreciate the constructivist approach to education; I > didn't "get it" until I came to appreciate the notion of allowing children > to come to "aha" moments on their own. The fact that children do fine > without manuals at the present level of interaction is a testament to the > design of the computer and the philosophy behind it. As generation xo grows > older, I think they will want to get deeper into the systems, and as they > do, I think they will want more information, and I'd like to help make that > freely available. > > I think a user manual or documentation will be more helpful for adult > learners who will end up participating in the laptop community, and who > would find it helpful to have something to refer to. Perhaps users could > learn many things simply by exploring, and yet they might appreciate having > something to turn to. Other people may not have personal possession of a > laptop, but would be interested in learning how they could support the > project. Some people who order the laptops through www.xogiving.org will > get frustrated with the laptop if they have no resources to turn to, and I'd > like to help them have fun. > > I think the idea of encouraging children to help each other learn is > wonderful; I also appreciate the principle of inclusiveness, and I think > that one way to be inclusive is to address various learning styles. > > On 10/15/07, Steve Fullerton <[EMAIL PROTECTED]> wrote: > > > > Hi Ed and all, > > > > I fully appreciate the detail. However, IMHO I think that there is some > > re-thinking required re: the traditional "user" documentation. The core of > > the OLPC (literally one laptop per child; the model does not work as well if > > there is not possession of a laptop for each child) is that of > > collaboration. > > > > One child learning something and then teaching his/her classmates. OLPC > > machines are not meant to be used in isolation. You could actually make a > > credible argument that user manuals are bad for the project. > > > > The highly intuitive design of Sugar and the experience of the pilots > > bears this out. The children seem to do just great without manuals, > > discovery is enhanced, and many of the constructionist ideals are realized. > > > > What do you think? > > > > On 10/15/07, Ed Trager < [EMAIL PROTECTED]> wrote: > > > > > > Hi, Michael, > > > > > > Just a few comments for consideration by everyone: > > > > > > > ... > > > > Doc writing conventions: > > > > > > > > Some linguistic research has been done on "simplified English" as a > > > > subset of English to use for low-level learners, and I think that it > > > > > > > might be a good place to look for ways to simplify the source_docs. > > > > But just thinking intuitively, I have cooked up the following > > > > suggestions in order to generate discussion: > > > > > > > > * Pronouns. > > > > o Use the first-person singular pronoun "I" to represent > > > the > > > > author of the docs, > > > > o the second-person singular pronoun "you" to represent > > > the > > > > reader of the docs, and > > > > o the first-person plural pronoun "we" to represent the > > > OLPC project. >
Fwd: Children's documentation
-- Forwarded message -- From: Bill Gearhart <[EMAIL PROTECTED]> Date: Oct 15, 2007 9:29 AM Subject: Children's documentation To: [EMAIL PROTECTED], Todd Kelsey <[EMAIL PROTECTED]> Anne, You mentioned looking for good children's doc w/Webkinz, etc. The prior gold standard was Lego building blocks. Cross culture and cross reading-ability (or "no" reading ability). I use their examples in my minimalism workshop. http://www.lego.com/en-US/default.aspx The 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 I'll dig up some others, but not having kids, I don't have a ready-made research lab ;-) --Bill -- Todd Kelsey 630.808.6444 ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: slightly long and detailed proposal for documentation-translation workflow
I am amazed and inspired by all the wonderful projects and activities that have arisen from the laptop project -- and though I was skeptical at first, I have also come to appreciate the constructivist approach to education; I didn't "get it" until I came to appreciate the notion of allowing children to come to "aha" moments on their own. The fact that children do fine without manuals at the present level of interaction is a testament to the design of the computer and the philosophy behind it. As generation xo grows older, I think they will want to get deeper into the systems, and as they do, I think they will want more information, and I'd like to help make that freely available. I think a user manual or documentation will be more helpful for adult learners who will end up participating in the laptop community, and who would find it helpful to have something to refer to. Perhaps users could learn many things simply by exploring, and yet they might appreciate having something to turn to. Other people may not have personal possession of a laptop, but would be interested in learning how they could support the project. Some people who order the laptops through www.xogiving.org will get frustrated with the laptop if they have no resources to turn to, and I'd like to help them have fun. I think the idea of encouraging children to help each other learn is wonderful; I also appreciate the principle of inclusiveness, and I think that one way to be inclusive is to address various learning styles. On 10/15/07, Steve Fullerton <[EMAIL PROTECTED]> wrote: > > Hi Ed and all, > > I fully appreciate the detail. However, IMHO I think that there is some > re-thinking required re: the traditional "user" documentation. The core of > the OLPC (literally one laptop per child; the model does not work as well if > there is not possession of a laptop for each child) is that of > collaboration. > > One child learning something and then teaching his/her classmates. OLPC > machines are not meant to be used in isolation. You could actually make a > credible argument that user manuals are bad for the project. > > The highly intuitive design of Sugar and the experience of the pilots > bears this out. The children seem to do just great without manuals, > discovery is enhanced, and many of the constructionist ideals are realized. > > What do you think? > > On 10/15/07, Ed Trager <[EMAIL PROTECTED]> wrote: > > > > Hi, Michael, > > > > Just a few comments for consideration by everyone: > > > > > ... > > > Doc writing conventions: > > > > > > Some linguistic research has been done on "simplified English" as a > > > subset of English to use for low-level learners, and I think that it > > > might be a good place to look for ways to simplify the source_docs. > > > But just thinking intuitively, I have cooked up the following > > > suggestions in order to generate discussion: > > > > > > * Pronouns. > > > o Use the first-person singular pronoun "I" to represent the > > > author of the docs, > > > o the second-person singular pronoun "you" to represent the > > > reader of the docs, and > > > o the first-person plural pronoun "we" to represent the OLPC > > project. > > > > > > o Examples. "We have designed a screen that switches to > > > black-and-white to conserve energy. I will explain how to switch your > > > screen to black-and-white. First, you press the X button on your > > > keyboard" Because we want the docs to be easily translated and > > > easily understood, the tone should be personal, using "I" for the > > > voice of the writer. This will be easier for amateur translators to > > > translate and easier for younger readers to understand. This will also > > > help the writer avoid the passive construction, which is very > > > difficult for some non-native English speakers to understand. > > > > I agree completely that the English passive construction should be > > avoided at all times. > > > > I mostly agree with your suggestion on use of pronouns. Use of "I" > > and "we" are fine. > > > > REGARDING THE PRONOUN "YOU" IN ENGLISH: > > -- > > > > However, as a native English speaker, I find the use of the pronoun > > "you" in the imperative mood often quite jarring. > > > > Imperative sentences in which the "you" is absent are understood by > > native sp
Re: slightly long and detailed proposal for documentation-translation workflow
Hi Ed and all, I fully appreciate the detail. However, IMHO I think that there is some re-thinking required re: the traditional "user" documentation. The core of the OLPC (literally one laptop per child; the model does not work as well if there is not possession of a laptop for each child) is that of collaboration. One child learning something and then teaching his/her classmates. OLPC machines are not meant to be used in isolation. You could actually make a credible argument that user manuals are bad for the project. The highly intuitive design of Sugar and the experience of the pilots bears this out. The children seem to do just great without manuals, discovery is enhanced, and many of the constructionist ideals are realized. What do you think? On 10/15/07, Ed Trager <[EMAIL PROTECTED]> wrote: > > Hi, Michael, > > Just a few comments for consideration by everyone: > > > ... > > Doc writing conventions: > > > > Some linguistic research has been done on "simplified English" as a > > subset of English to use for low-level learners, and I think that it > > might be a good place to look for ways to simplify the source_docs. > > But just thinking intuitively, I have cooked up the following > > suggestions in order to generate discussion: > > > > * Pronouns. > > o Use the first-person singular pronoun "I" to represent the > > author of the docs, > > o the second-person singular pronoun "you" to represent the > > reader of the docs, and > > o the first-person plural pronoun "we" to represent the OLPC > project. > > > > o Examples. "We have designed a screen that switches to > > black-and-white to conserve energy. I will explain how to switch your > > screen to black-and-white. First, you press the X button on your > > keyboard" Because we want the docs to be easily translated and > > easily understood, the tone should be personal, using "I" for the > > voice of the writer. This will be easier for amateur translators to > > translate and easier for younger readers to understand. This will also > > help the writer avoid the passive construction, which is very > > difficult for some non-native English speakers to understand. > > I agree completely that the English passive construction should be > avoided at all times. > > I mostly agree with your suggestion on use of pronouns. Use of "I" > and "we" are fine. > > REGARDING THE PRONOUN "YOU" IN ENGLISH: > -- > > However, as a native English speaker, I find the use of the pronoun > "you" in the imperative mood often quite jarring. > > Imperative sentences in which the "you" is absent are understood by > native speakers of English to convey a softer, less imperative tone. > Such sentences are considered more polite. Compare: > > (A) "First you press the X button on the keyboard." > > ... versus: > > (B) "First, press the X button on the keyboard." > > One or two instances of "you" in imperatives or directions in spoken > or written English may not seem too bad, but after a series of them, > it becomes irritating. > > So while I have no objection to simple English which will be easily > understood by younger learners of the language, we must also be sure > that we do not proscribe an incorrect idea regarding the usage of the > pronoun "you" in imperative sentences in English. > > In short, it is *not* OK to use "you" repeatedly in a series of > imperatives or directions (such as instructions for using a laptop). > The absence of the pronoun "you" is preferred when giving directions > in English. > > REGARDING POSSESSIVE PRONOUNS: > --- > > Look again at the sentances Michael used for his example: > > > I will explain how to switch your screen to black-and-white. > > First, you press the X button on your keyboard" > > English speakers make frequent use of possessive pronouns, as is the > case here with : "your screen" , "your keyboard" . > > But in many other languages (perhaps most other languages?) we would > not use possessive pronouns here at all. All of these English > "your"s, if translated quite directly into foreign languages, results > in very annoying and unnatural sounding texts in my experience. > > So I would advise we try to fix the English from the start by avoiding > unecessary i
Re: slightly long and detailed proposal for documentation-translation workflow
Hi, Michael, Just a few comments for consideration by everyone: > ... > Doc writing conventions: > > Some linguistic research has been done on "simplified English" as a > subset of English to use for low-level learners, and I think that it > might be a good place to look for ways to simplify the source_docs. > But just thinking intuitively, I have cooked up the following > suggestions in order to generate discussion: > > * Pronouns. > o Use the first-person singular pronoun "I" to represent the > author of the docs, > o the second-person singular pronoun "you" to represent the > reader of the docs, and > o the first-person plural pronoun "we" to represent the OLPC > project. > > o Examples. "We have designed a screen that switches to > black-and-white to conserve energy. I will explain how to switch your > screen to black-and-white. First, you press the X button on your > keyboard" Because we want the docs to be easily translated and > easily understood, the tone should be personal, using "I" for the > voice of the writer. This will be easier for amateur translators to > translate and easier for younger readers to understand. This will also > help the writer avoid the passive construction, which is very > difficult for some non-native English speakers to understand. I agree completely that the English passive construction should be avoided at all times. I mostly agree with your suggestion on use of pronouns. Use of "I" and "we" are fine. REGARDING THE PRONOUN "YOU" IN ENGLISH: -- However, as a native English speaker, I find the use of the pronoun "you" in the imperative mood often quite jarring. Imperative sentences in which the "you" is absent are understood by native speakers of English to convey a softer, less imperative tone. Such sentences are considered more polite. Compare: (A) "First you press the X button on the keyboard." ... versus: (B) "First, press the X button on the keyboard." One or two instances of "you" in imperatives or directions in spoken or written English may not seem too bad, but after a series of them, it becomes irritating. So while I have no objection to simple English which will be easily understood by younger learners of the language, we must also be sure that we do not proscribe an incorrect idea regarding the usage of the pronoun "you" in imperative sentences in English. In short, it is *not* OK to use "you" repeatedly in a series of imperatives or directions (such as instructions for using a laptop). The absence of the pronoun "you" is preferred when giving directions in English. REGARDING POSSESSIVE PRONOUNS: --- Look again at the sentances Michael used for his example: > I will explain how to switch your screen to black-and-white. > First, you press the X button on your keyboard" English speakers make frequent use of possessive pronouns, as is the case here with : "your screen" , "your keyboard" . But in many other languages (perhaps most other languages?) we would not use possessive pronouns here at all. All of these English "your"s, if translated quite directly into foreign languages, results in very annoying and unnatural sounding texts in my experience. So I would advise we try to fix the English from the start by avoiding unecessary invocations of possessive pronouns, especially "your": I will explain how to switch the screen to black-and-white. First, press the X button on the keyboard" I basically agree with the rest of Michael's suggestions, so that's all the comments I have. -- Ed Trager ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: documentation-translation workflow
Wonderful! Helping to put together volunteers; 3 technical writers have made themselves available for assisting with documentation; anyone who is interested in helping work out the "collaborative tools/localization tools" -- please touch base. They are interested in serving the OLPC project and am suggesting that strategy be developed for channeling more volunteers -- then I expect there will be more -- discussing assigning a writer to each activity if we are so lucky. Comments: *reading level* - 100% agree on simplified technical english. great if developers/others can use simplified english in original note-taking. if you have ms word you can run a test that calculates age level - 6th grade is probably good. if you don't have ms word you can send an open office doc or wiki url where you are taking notes. *screenshots* - visuals are important. beyond providing reference material on "how" -- helpful if developers can think of a step by step scenario that someone can walk through to "try" the activity. when writing books I found it helpful to walk through a process/task, and take screenshots, drop them into a document, then go back and write captions -- then as necessary filling in with background info - good to think of whether you can provide a concept, task or reference. all three categories are helpful - suggest taking screenshots in as small a format as possible; if you take the entire screen and can crop to the relevant section, great -- otherwise in caption you could include notes to crop to a certain area - for localization of screenshots, suggest not worrying about in-language text for now -- but that localization filenaming convention be established for naming screenshots. immediate term: blah-en or blah-sp. not clear on if OLPC has decided on ISO language codes. *tools* - have been working on looking at various tools for documentation/localization; if interested/working on such things, please get in touch. I will subscribe to [EMAIL PROTECTED] (btw Idiom has donated an instance of idiom worldserver that can be studied as a method of incubating open source alternative, trying to find configuration help.) *portal* - started google group recently as repository for documentation strategy, files and information, and as temporary method of corralling/versioning content, and for having an email list. could be precursor to [EMAIL PROTECTED] -- if interested, touch base. *localization* Lingo Systems stepped up to the plate with build 542 notes and helping to get translated into 7 different languages; not sure about this time around. probably most scalable approach will be to do things in stages, using a "human content management system" until more automation can occur. Suggesting 3 stages - alpha - beta (draft) - publis > alpha: have a dynamic wiki-based alpha TOC, from which a "TOC code freeze" can be made by tech writers working back from translation deadline, pulling TOC into editing, then pulling content in from the live wiki pages where notes are and editing > beta: dropping TOC and pages into beta wiki pages and pursuing 3 channel localization strategy (until something better can be found) -- channel 1: translation can occur directly within wiki page (not ideal, no translation memory, can be time consuming and prone to human error) or copy and pasted into word along with note that it is being translated - channel 2: as content is dropped into beta wiki page, it is also placed on wordpress - advantage here is simply that we can connect to world wide lexicon which has a distributed translation roundtrip solution -- channel 3: putting content into word processing documents and circulating to professional translators if/as available, who often prefer RTF format. > publishing: based on what translations are available, printing out chapters/modules from TOC code freeze out to PDF and HTML. Practical world -- for upcoming release -- my understanding is we have a little under two weeks, and that the "translation freeze" should be by midnight this friday EST -- this would be for any documentation that is being handled already -- we've already been working on aggegrating notes, links to existing wiki pages, and massaging previous notes. so the goal at the moment for this release is simply to get something better and more cohesive than build 542 notes -- problem is translation. not sure if lingo will come through, at this point need volunteers; ideally professional bilingual technical writers but any translation will help. it's wasteful not to have all of this in a cms so we could just send the "new" material for translation but it would be too time consuming to go through and calculate localization based on x-diffs from wiki pages (unless someone knows of an existing, working, wiki-based translation management plug-in), so we restarted documentation from scratch. so the following languages are needed
slightly long and detailed proposal for documentation-translation workflow
I sent these ideas to Jim Gettys, who suggested that I send them to the development and localization mailing lists. -- Summary: * Write/ Edit primary documentation according to an explicit set of writing conventions designed to minimize ambiguity and complexity in order to facilitate translation. * Treat this English documentation as source code which is meant to be translated/compiled into user languages. * Use/Create collaboration tools to make translation, distribution, and maintenance of docs more efficient. -- Assumptions: Some of those doing translation will not be professional translators fully bilingual in English and the target language. They might be any of the following: * a village teacher who speaks the target language as her first language (L1) and English as a weak second language (L2); * a missionary who speaks English as L1 or L2 (in the case of a French missionary in Africa, for example) and the target language as a weak L3; * a professional translator who speaks a non-English L1, reads and writes the target language as L2, and knows English as just a subject that he or she studied in school and uses for travel; * a native L1 speaker of the target language who has immigrated to a foreign country in which English is spoken as a primary or secondary language. Many of the translators are not going to be career translators, so rather than having the translator accommodate the source text, the source text should accommodate the translator. Documentation translation is particularly difficult because of how documentation is usually created. Often docs are written grudgingly at the end of the project, and docs are rarely written to a uniform format or set of conventions. There is little reflection on what kind of docs are needed, and docs are usually not edited before they are sent off for transl and publishing. The conventional approach to translation is that, when a novel or academic article is translated, it is the burden of the translator to accommodate the original, and if the original is unclear, this lack of clarity is translated into the target texts because the target text must be a mirror of the original. I know this from direct experience, having been the translator for many doc jobs from Japanese companies. The originals are often incomprehensible because of ambiguity and inconsistency, as in the following examples: * different sections of the docs are written by different people using different terminology for the same processes and entities; * unconfident writers are too brief, assuming background info and context to which the translator does not have access; * more confident writers use too many idioms and colorful expressions, rambling on and on in extended and poorly-organized complex sentences; * section divisions and overall organization are inconsistent, forcing the translator to restructure the original before beginning the translation; * ambiguities inherent in the language itself (like the absence of gendered pronouns and explicit sentence subjects in Japanese) also complicate the translation, forcing the translator to contact the writer of the original, thus slowing the process and degrading translator motivation and confidence. Ambiguity is the biggest obstacle to translation. If it is a rush job (and it always is), and especially if the translation is being handled by a middleman like a publisher or web design firm (and these days it almost always is), the translator usually retreats to literal translation in the face of ambiguity because there is no way to contact the author (middlemen don't want the translator to know how much the client is being billed for translation) or no time to wait for the reply. When the text is unclear, the translator has no choice but to translate the ambiguity itself. In the case of OLPC documentation, ambiguity should be avoided at all costs. Anything that interferes with teachers and students using the notebooks should be avoided, and bad docs would certainly be frustrating and demotivating for the educators and pupils. In order to have translations that are as clear as possible, we must have source-docs that are as clear as possible. -- Reconception of documentation/ translation as parallel to computer programming: The OLPC team uses English as a common working language, but the users will be using translations, so the English documentation can be seen as not a product in and of itself but as the source for all translations. The English-language "source docs" should be written to a set of conventions meant to reduce ambiguity and ensure consistency, even when doing so necessitates violating conventional English writing style. The set of documentation standards I am proposing is similar to the set of coding conventions a programmer follows. The "source docs" (though written in English) should be seen as source code which is then compiled (or
