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" <[EMAIL PROTECTED]> > Subject: [OLPC library] DEADLINE, was: updating of the docs on FLOSS > Manuals > To: "Anne Gentle" <[EMAIL PROTECTED]> > Cc: Library-OLPC <[email protected]> > Message-ID: > <[EMAIL PROTECTED]> > 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 <[EMAIL PROTECTED]> 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 >> [email protected] >> 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 > > > ------------------------------ > _______________________________________________ Library mailing list [email protected] http://lists.laptop.org/listinfo/library
