[OLPC library] DEADLINE

Thu Sep 4 17:20:15 EDT 2008

Hi Guys,

I read this link online in FF3 on XP: http://en.flossmanuals.net/xo

I made the following comments with an eye towards what I would like to 
see in this manual when it is included in the 8.2 release image.

0 - Nice job! Its great to see all of this documentation organized in 
one place.

1 - Introduction: "The XO's software is known as Sugar" to "The 
graphical interface on the XO is called Sugar" and add a link to the 
sugar manual.

2 - Introduction: let's make sure to read these pages on an XO! I'm not 
in front of mine right now but I hope someone tried that.

3 - About OLPC: I'm not sure where that text came from. Looks OK to me 
but should probably be cleared by more people. Alternatively we could 
use Mission blurb here: http://www.laptop.org/en/vision/index.shtml

4 - Keyboard shortcuts: We should add a note saying that not all of 
these short cuts will work in all activities. I see that for the view 
source one but it may also apply to the cut, copy and paste ones too. I 
don't think all activities support that.

5 - Storage: We should add a sentence that says: "If your XO Flash Disk 
fills up completely your XO will not operate properly. If that happens, 
on the next boot, the system will automaticaly delete the largest file 
on your system." What happens with release 8.2 is that the system should 
pop up a warning dialog if you NAND is getting full (not sure of the 
exact threshold). If you still add files until it is full then on the 
next boot it runs a script which prompts you once to enter "c" to 
continue. If you don't choose "c" it starts deleting largest file first 
until there is 20MB free. If you choose "c" it continues to boot and you 
get to the sugar GUI but you can't use the journal (usually crashes). 
All you can do is open terminal and try deleting things from there. If 
someone has time I can connect you to the developers to document this in 
more detail.

6 - Charging battery: Not sure you can or should connect you XO cable to 
a car battery. I would take that out. I think it needs to be plugged in 
the "the wall". That is to a 120AC power source or whatever is the power 
source standard in your country and for the XO's adapter.

7 - Charging battery: This sentence sounds a little optimistic: "Any 
charger whose jack fits into the XO's power port and outputs between 11 
and 18 volts should work." We should say 11 - 18 volts DC at a minimum. 
Probably need to say that the polarity of the plug has to be correct too.

8 - Give me the internet: You can't really connect to a "school server". 
That is either a wired or wirelss network connection. The school server 
is just a computer that performs network and file services. It does not 
make the L2 or L1 connection to the network. I suggest removing the 
school server bullet.

9 - Give me the internet: Before you connect section. This sentence is 
confusing: "Access points that represent the Mesh network are indicated 
with a target icon" Its not actually an access point. Its another Xo you 
are connecting to or more specifically its a mesh channel you are using 
to exchange data.

10 - Give me the internet: connecting to the internet section. We should 
probably add that not all access points are supported. Depending on 
encryption standard and configuration, some may not allow the XO to connect.

11 - Nice troubleshooting section!

12 - Networking hardware ToC name is Networking Hardware but the page is 
called external hardware.

13 - Maintaining your XO: say maintaining the XO involves updating your 
firmware. I don't think that's true. In general I would stay away from 
firmware updates. The main thing is to update to new releases as 
needed/desired. That will bring along the new firmware. I suggest you 
take out the firmware references. Also, add a note saying to read the 
release notes carefully before upgrading. Not every new release is 
recommended for every user.

14 - I leave the review of how to reflash to Scott :-)

I also printed out http://en.flossmanuals.net/sugar

I read it with an eye towards what it should look like when its included 
  in the 8.2 shipping image for the XO. I hope that is the intention of 
this manual.

1 - I noticed that the notes and links are not printed. Notes would be 
nice and underlines on anything that's a URL.

2 - Page 1 "What is Sugar". Add a sentence that "Sugar is the name of 
the graphical user interface on the XO".

3 - Page 1 Take out "It is almost impossible to lose data". That may be 
a design goal but its not true yet. Use the second sentence as the main 
point.

4 - Page 3: Getting Sugar. Remove the whole section. If you are reading 
this on an XO you have sugar.

5 - Remove whol Sugar on Ubuntu. No problem for the sugar manual but not 
  needed in the manual we ship with the XO.

6 - Page 18 Frame control panel: Is it really a range of 00.1 to .999 
seconds? (I should be doing this in front of an XO :-(. Seems odd. I 
thought you could get in to multiple seconds range.

7 - Page 19 Languages control panel. Add a note saying that not all 
languages are installed or available. Also that many of the choices will 
be the same (e.g. I think all the English ones are the same and same 
with Spanish etc.)

8 - Page 21 Power management panel. Add a sentence saying that Extreme 
mode does the same things as Automatic mode plus it turns off the radio. 
As its written it seems like it just turns off the radio. Also, typo on 
"dimmes". BTW it looks like we will have some significant open bugs in 
this area for 8.2. The main thing is that in automatic power save you 
may lose your network connection when it dims. Its not final yet and I 
will try to document the known problems in the release notes. In 
general, we should link to the release notes prominently and suggest 
people check the unresolved bugs section somewhere at the top of the manual.

9 - Page 21 Software updates control. I don't it actually fetches a list 
of all available activities. I think it checks for ones that you already 
have installed and it checks for a set of activities defined by some URL 
(perhaps the G1G1 activities). Most likely the G1G1 activity list here: 
http://wiki.laptop.org/go/Activities/G1G1 but it may vary depending on 
what image was manufactured on your XO. See the background docs on this 
feature at: http://wiki.laptop.org/go/Software_update

10 - page 27 Sugar User interface. I don't think many activities support 
the view source option. Double check that and we should test the browse 
example too. You should probably change "you don't need to double click" 
to "don't double click as its unnecessary.". In 8.2 you can open two 
instances of an activity by double clicking on its icon and that cause 
un-anticpated results. Also double negative typo at "you won't have no 
messy..." and missing space at end of that sentence.

11 - Page 27 For parents and teachers section of Sugar UI section: 
"Every activity has the potential to be a networked activity" may be 
true but misleading. And there are different kinds "networking" 
depending on the activity. Anything is possible some day but only a 
subset of activities have collaboration capabilities right now.

12 - Page 28, Home View secton. Should add the "all" to the list view 
section. That is the only view that shows all activities, favorite or not.

13 - Page 31. XO menu. We need to document the "register" menu option. 
This is used to connect the XO to a School Server to allow the school 
server to track this XO for backup of files and other features. If you 
do not have a school server then this menu item will not have an affect. 
If you do have a school server this menu item will disappear after the 
XO registers with it.

14 - Page 33 Activity View: Typo in bullet 1. Second "that" should be "at".

15 - In the Views section (Home view, group view etc) there are 
references to F1, F2 etc. The keys aren't named that on the XO. We 
should use the key name or some other way to refer to them. Same with 
alt-esc. I think that means Alt - X key in the upper right corner. I see 
that in other areas too...

15 - Page 44 Journal section. Bullet 1. I don't think the star does 
anything right now. Its says that is never deleted. We should check 
that. I assume that means you can't delete it manually in the normal method.

16 - Page 48 Removable Media.
There is likely to be a serious open bug in 8.2 that causes the GUI to 
show the USB key unmounted but it is not actually unmounted. If you take 
the key out in that state you can corrupt it! See: 
http://dev.laptop.org/ticket/7993 This only happens if you also have a 
terminal window open and you are accessing the USB key via some 
command/program in that terminal. Mostly FYI. Not sure we need to 
document this here. If you can find a diplomatic way to say you can 
recommend that people shut down the XO before removing the USB key for 
safest operation.

That's it! I scanned the activity section and didn't read the Connecting 
and maintenance sections under the assumption they are the same as those 
in the XO manual.

I hope that's helpful. In general, unless I say something is definitely 
wrong you can take these as suggestions. Let me know if anything is not 
clear or you need more info.

This is making me a feel a lot better about just having a stub of info 
in the release notes and a link to the full doc! Please send me the 
final URL and I wll put it in the release notes for 8.2.

Can I go home now Seth! :-)

Thanks,

Greg S

> Date: Tue, 2 Sep 2008 21:49:50 +0000
> From: "Seth Woodworth" <seth at laptop.org>
> Subject: [OLPC library] DEADLINE, was: updating of the docs on FLOSS
> 	Manuals
> To: "Anne Gentle" <annegentle at gmail.com>
> Cc: Library-OLPC <Library at lists.laptop.org>
> Message-ID:
> 	<b54bd10a0809021449m6c13007as7f5d7f309d1877e3 at mail.gmail.com>
> Content-Type: text/plain; charset="iso-8859-1"
> 
> Hey everybody,  Thank you all so much for participating in the BookSprint.
> This manual looks great and is going to be a huge help.
> 
> As far as packaging this book goes, we need to finalize updates by Friday or
> the changes wont make it into the shipped manual on the XO.  So please make
> the most important updates quickly.
> 
> After Friday there is still going to be a huge need for ongoing
> documentation. Keep up the excellent work everybody!
> 
> All the best,
> Seth Woodworth
> 
> On Tue, Sep 2, 2008 at 8:05 PM, Anne Gentle <annegentle at gmail.com> wrote:
> 
>> Hi everyone,
>> Having had a nice 3-day weekend to recover from the high-energy week of the
>> BookSprint, I wanted to give you some ideas for maintenance of the manuals
>> going forward.
>>
>> Daniel's review of the manuals was extremely helpful and I believe we've
>> incorporated all his suggestions. If you only have time to read and write up
>> notes, sending an email to the Library list is a good way of getting your
>> suggestions to the writers. Or, as Adam Hyde suggested, make the changes
>> yourself, but if you simply don't have time for that, an email listing your
>> review comments is perfectly acceptable.
>>
>> Documentation in some organizations is an integral part of the development
>> process, and you can log and track bugs against the documentation. The OLPC
>> Trac system can do this to a point, but there is a lot of signal to noise
>> there for writers to keep up with. I'd personally prefer that you use the
>> FLOSS Manuals wiki system to either go ahead and make the changes yourself,
>> or comment on the chapter that you have suggestions for, or email your
>> comments to either me or this list.
>>
>> As the maintainer, I'll be keeping an eye on all changes and all comments
>> to the manuals. We've already got a good comment from someone saying that
>> since the networking chapter addresses 8.2, how about creating another
>> chapter for the 6nn and 7nn deployments that are active today? With FLOSS
>> Manuals remix capability, this request seems do-able. I'd like to hear
>> commentary on that from this group though.
>>
>> For additional concepts that you do not feel are covered in the manuals but
>> are not "bugs" technically with the manual, please post to this Library list
>> so that me or one of the other community writers can find a way to
>> incorporate it.
>>
>> I believe my role going forward is a central person for doc requests, but I
>> do want to build redundancy in the system so I'm not the only resource
>> available for doc.
>>
>> Thanks all for your contributions last week, and I look forward to
>> continued improvement as we go forward.
>>
>> Anne
>>
>> _______________________________________________
>> Library mailing list
>> Library at lists.laptop.org
>> http://lists.laptop.org/listinfo/library
>>
>>
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: http://lists.laptop.org/pipermail/library/attachments/20080902/1e29f6f6/attachment-0001.htm 
> 
> ------------------------------
> 