Re: Potential volunteer offering technical writing
On 30 September 2011 19:51, Tabitha Roder tabi...@tabitha.net.nz wrote: Hi If we had a volunteer (English Native language) professional technical writer, what writing would be of most use to OLPC or Sugar that we can point her in the direction of? She currently works with developers to write end user documentation. Thanks Tabitha - NZ volunteers I think the most important thing is to identify and focus on the target audience - is the documentation meant for technical users, end users, teachers, children...? We (OLPC Australia) would be happy to suggest ways in which the documentation can be improved, using our experience from working directly with teachers and communities. Our online course (http://laptop.moodle.com.au/ - you can log in as a guest) might provide some inspiration. Our Education Manager has some advice, based on her experiences with reading the publicly-available documentation: - Make sure the Sugar and XO Floss manuals are up-to-date, easily readable and have all the necessary information. - Externally available documentation: It’s imperative that minimal knowledge is assumed, which I think is the hardest part. Pages need to have less information rather than more, good user interfaces, lots of useful images, clear headings and language that is simple and precise. My concern with a lot of the external documentation is that it is sometimes overwhelming, difficult to navigate (both between pages and within them) and written for a technical audience rather than a basic user. Trying to target both a technical audience and a basic user in the same documentation means you are more likely to lose the basic user. Perhaps some of this documentation needs to be separate out. The main issue I see with the Wiki is that it’s difficult to navigate and find information from the menus. This isn’t, per say, the role of a technical writer, but tidying up navigation in the Wiki would make it more accessible. - Someone to simply document the activities available (purpose of the activity, how to use it, any tips that are not easily discoverable, and what you can DO with it- exemplars of use) - There are lesson ideas and examples of practice all over the place. It would be amazing to synthesise this as much as possible, so they are not so difficult and time consuming to find, and to put them in a uniform format. I’m not sure what the best way to approach this is, but from an educational perspective, knowing not just HOW to use the XOs but WHAT to do with them is far more important. Making these ideas easily accessible, in my mind, is quite important. Sridhar ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
On Mon, Oct 31, 2011 at 1:45 AM, Sridhar Dhanapalan srid...@laptop.org.auwrote: On 30 September 2011 19:51, Tabitha Roder tabi...@tabitha.net.nz wrote: Hi If we had a volunteer (English Native language) professional technical writer, what writing would be of most use to OLPC or Sugar that we can point her in the direction of? She currently works with developers to write end user documentation. Thanks Tabitha - NZ volunteers I think the most important thing is to identify and focus on the target audience - is the documentation meant for technical users, end users, teachers, children...? That's indeed the key question which we also spent some time discussing in San Francisco. The current Help activity + corresponding FlossManuals was mainly written with Give 1, Get 1 users in mind so there's definitely quite some rework that needs to be done if we're looking to cater to other audiences. We (OLPC Australia) would be happy to suggest ways in which the documentation can be improved, using our experience from working directly with teachers and communities. Our online course (http://laptop.moodle.com.au/ - you can log in as a guest) might provide some inspiration. Thanks, I'll take a look:-) Our Education Manager has some advice, based on her experiences with reading the publicly-available documentation: - Make sure the Sugar and XO Floss manuals are up-to-date, easily readable and have all the necessary information. - Externally available documentation: It’s imperative that minimal knowledge is assumed, which I think is the hardest part. Pages need to have less information rather than more, good user interfaces, lots of useful images, clear headings and language that is simple and precise. My concern with a lot of the external documentation is that it is sometimes overwhelming, difficult to navigate (both between pages and within them) and written for a technical audience rather than a basic user. Trying to target both a technical audience and a basic user in the same documentation means you are more likely to lose the basic user. Perhaps some of this documentation needs to be separate out. The main issue I see with the Wiki is that it’s difficult to navigate and find information from the menus. This isn’t, per say, the role of a technical writer, but tidying up navigation in the Wiki would make it more accessible. - Someone to simply document the activities available (purpose of the activity, how to use it, any tips that are not easily discoverable, and what you can DO with it- exemplars of use) That point is also on our agenda: http://wiki.laptop.org/go/OLPC_SanFranciscoBayArea/OLPCSF_Community_Summit_2011/Help_Activity_Refresh#Revised_Manual_Contents - There are lesson ideas and examples of practice all over the place. It would be amazing to synthesise this as much as possible, so they are not so difficult and time consuming to find, and to put them in a uniform format. I’m not sure what the best way to approach this is, but from an educational perspective, knowing not just HOW to use the XOs but WHAT to do with them is far more important. Making these ideas easily accessible, in my mind, is quite important. Also something that was discussed various times in San Francisco (and previously Paris). It definitely sounds like at least Australia, the Philippines, Jamaica, Madagascar - Nosy Komba, and Austria have some common needs here which I think we should expand on in a seperate thread. :-) Cheers, Christoph -- Christoph Derndorfer editor, OLPC News [www.olpcnews.com] volunteer, OLPC (Austria) [www.olpc.at] e-mail: christ...@derndorfer.eu ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Potential volunteer offering technical writing
On 20 October 2011 11:21, Christoph Derndorfer christoph.derndor...@gmail.com wrote: not sure what the exact time difference is between San Francisco and NZ but maybe we could set up a Skype call between Rachel, you, and us in SF to coordinate our documentation efforts? Cheers, Christoph We meet on Saturday mornings at 11am NZ time (that is Friday 3pm in San Francisco) for olpc/sugar testing and we are on IRC #sugar #olpc and a bunch of other related freenode channels. We can also be on skype (tabitharoder). If we are a little bit late, don't worry (probably the baby is requiring my attention) as we won't be long. We are at testing usually until around 2pm, or later depending how much testing we have to do (and how well the baby is coping). Tabitha ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Potential volunteer offering technical writing
On 4 October 2011 16:18, Martin Langhoff martin.langh...@gmail.com wrote: And the FLOSS Manuals feed into the Help Activity, so work there pays of many times over... So how do we feed the FLOSS manual into the Help activity? Rachel is keen to help, but keen to see her work on the XO. Is the FLOSS - help activity process documented anywhere? I don't think we are able to help with improving the i10n process or the activity build process, but we can help with the (english) words themselves. ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Potential volunteer offering technical writing
We need help writing, and translating in FLOSS. I can help updating the activity. Gonzalo On Wed, Oct 19, 2011 at 4:53 PM, Tabitha Roder tabi...@tabitha.net.nzwrote: On 4 October 2011 16:18, Martin Langhoff martin.langh...@gmail.comwrote: And the FLOSS Manuals feed into the Help Activity, so work there pays of many times over... So how do we feed the FLOSS manual into the Help activity? Rachel is keen to help, but keen to see her work on the XO. Is the FLOSS - help activity process documented anywhere? I don't think we are able to help with improving the i10n process or the activity build process, but we can help with the (english) words themselves. ___ 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: Potential volunteer offering technical writing
Tabitha, not sure what the exact time difference is between San Francisco and NZ but maybe we could set up a Skype call between Rachel, you, and us in SF to coordinate our documentation efforts? Cheers, Christoph Am 19.10.2011 22:49 schrieb Gonzalo Odiard gonz...@laptop.org: We need help writing, and translating in FLOSS. I can help updating the activity. Gonzalo On Wed, Oct 19, 2011 at 4:53 PM, Tabitha Roder tabi...@tabitha.net.nzwrote: On 4 October 2011 16:18, Martin Langhoff martin.langh...@gmail.comwrote: And the FLOSS Manuals feed into the Help Activity, so work there pays of many times over... So how do we feed the FLOSS manual into the Help activity? Rachel is keen to help, but keen to see her work on the XO. Is the FLOSS - help activity process documented anywhere? I don't think we are able to help with improving the i10n process or the activity build process, but we can help with the (english) words themselves. ___ 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 ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Howtos within Sugar Activities (was: Potential volunteer offering technical writing)
The problem with this is localization. If we want achieve all the activities translated to all the needed languages (more than 110 active languages in pootle at this moment) you can see including manuals/howtos in the activities we will have a space problem. We are thinking in include a minimal help, like Implode activity or TurtleArt are doing, But with this minimal help, the TurtleArt po and locale directory are much bigger than all the other data in the activity. Gonzalo On Tue, Oct 11, 2011 at 6:21 AM, Bastien b...@altern.org wrote: I have read all the interesting input regarding refreshing the Help activity and collectively writing up new Sugar lessons. One simple idea: why not try to put howtos *within* Sugar Activities? For example, the Turtle Art activity would have such a folder: how/general-tutorial.txt how/drawing-a-square.txt how/playing-with-variables.txt how/... Plain text would be nice, as it could be later exported to HTML and displayed within Sugar when required. Plain text is also easier to handle wrt translation. There has been a lot of discussion about accessing the source and I see this how/ folder something that we could feed with powerful ideas, sitting between the source code and the activity. Also, it would help solving one of the biggest problem: having someone who is in charge of maintaining this documentation. FWIW, I have updated the FLOSS/DOCS presentation in which I summarize the background ideas and motivations for this proposal: http://lumiere.ens.fr/~guerry/the-four-letters-word-of-floss-docs.html Thanks, -- Bastien ___ Sugar-devel mailing list sugar-de...@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Howtos within Sugar Activities (was: Potential volunteer offering technical writing)
On Tue, Oct 11, 2011 at 6:23 AM, Gonzalo Odiard gonz...@laptop.org wrote: The problem with this is localization. If we want achieve all the activities translated to all the needed languages (more than 110 active languages in pootle at this moment) you can see including manuals/howtos in the activities we will have a space problem. We are thinking in include a minimal help, like Implode activity or TurtleArt are doing, But with this minimal help, the TurtleArt po and locale directory are much bigger than all the other data in the activity. Also, by including even simple help strings, the burden on the translator when from a few hundred single-word strings to many many long sentences. Even so, the real explanations are found in the wiki. I took a different approach in Turtle Confusion: I added hints in the form of short programs in the help. Not sure how to scale that approach. -walter Gonzalo On Tue, Oct 11, 2011 at 6:21 AM, Bastien b...@altern.org wrote: I have read all the interesting input regarding refreshing the Help activity and collectively writing up new Sugar lessons. One simple idea: why not try to put howtos *within* Sugar Activities? For example, the Turtle Art activity would have such a folder: how/general-tutorial.txt how/drawing-a-square.txt how/playing-with-variables.txt how/... Plain text would be nice, as it could be later exported to HTML and displayed within Sugar when required. Plain text is also easier to handle wrt translation. There has been a lot of discussion about accessing the source and I see this how/ folder something that we could feed with powerful ideas, sitting between the source code and the activity. Also, it would help solving one of the biggest problem: having someone who is in charge of maintaining this documentation. FWIW, I have updated the FLOSS/DOCS presentation in which I summarize the background ideas and motivations for this proposal: http://lumiere.ens.fr/~guerry/the-four-letters-word-of-floss-docs.html Thanks, -- Bastien ___ Sugar-devel mailing list sugar-de...@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel ___ Sugar-devel mailing list sugar-de...@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel -- Walter Bender Sugar Labs http://www.sugarlabs.org ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Howtos within Sugar Activities (was: [Sugar-devel] Potential volunteer offering technical writing)
I have read all the interesting input regarding refreshing the Help activity and collectively writing up new Sugar lessons. One simple idea: why not try to put howtos *within* Sugar Activities? For example, the Turtle Art activity would have such a folder: how/general-tutorial.txt how/drawing-a-square.txt how/playing-with-variables.txt how/... Plain text would be nice, as it could be later exported to HTML and displayed within Sugar when required. Plain text is also easier to handle wrt translation. There has been a lot of discussion about accessing the source and I see this how/ folder something that we could feed with powerful ideas, sitting between the source code and the activity. Also, it would help solving one of the biggest problem: having someone who is in charge of maintaining this documentation. FWIW, I have updated the FLOSS/DOCS presentation in which I summarize the background ideas and motivations for this proposal: http://lumiere.ens.fr/~guerry/the-four-letters-word-of-floss-docs.html Thanks, -- Bastien ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
Hi Martin, Could you please shed a light on which manuals in FlossManuals make up the Help Activity? Some of us who will be jumping in to refresh it don't know much about the history. Right, here I am not sure if you have seen: the current Help activity is a combination of several floss manuals mixed together. And it looks like it may have some tweaks and customizations. Thank you! ---Cherry On Wed, Oct 5, 2011 at 9:36 AM, Martin Langhoff martin.langh...@gmail.comwrote: On Wed, Oct 5, 2011 at 12:13 PM, Gonzalo Odiard gonz...@laptop.org wrote: As for the use of FLOSSManuals as the source and L10n workflow for the Help Activity, sadly, I think the more pressing challenge may be the lack of documentation of the process employed by Seth and his collaborators in the original Help Activity creation from FLOSSManual sources. I am not worried about that. Well, yes and no :-) The help activity is only a modified Browse activity with a lot of html files in a directory. I think there are different tasks and will be done by different people at different times: * Create a updated version of the documentation in Floss manuals. Yes * Update the help activity Right, here I am not sure if you have seen: the current Help activity is a combination of several floss manuals mixed together. And it looks like it may have some tweaks and customizations. * Translate the manuals (like we did with 'Make your own Sugar Activities') Yep, though I think on this track we all agree that you'd really make a different activity for each language... Would be good if the new manuals are cloned and we can keep the old ones to the users using the old version of Sugar +10 on this. Some Sugar versions are widely used... m -- martin.langh...@gmail.com 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
Re: [Sugar-devel] Potential volunteer offering technical writing
On Oct 6, 2011 6:28 PM, Cherry Withers cwith...@ekindling.org wrote: Could you please shed a light on which manuals in FlossManuals make up the Help Activity? Some of us who will be jumping in to refresh it don't know much about the history. To be honest, I don't really know. Here's what I know: - open the help activity - look at the left-panel navigation TOC - open the Sugar manual -- you'll see lots of topics aren't there! So the topics that aren't there are in general from manuals about a specific activity. There is also a flossmanual about the XO itself -- I think some chapters from there have been included. On flossmanuals, there is an option to make a book or something like that. When you do that, it lets you pick and order chapters from many manuals. Perhaps that's what's been done -- perhaps the mix was prepared on the flossmanuals website. It is trivial to see if you look at both the Help activity and the stuff on flossmanuals. cheers, m ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
I think what was used to generate the help was the FLOSS Manuals Remix feature, http://en.flossmanuals.net/index.php?plugin=remix . The workflow would be to identify the source of the existing help text starting with the Sugar and XO books. Edit the source material then use the remix feature. I would suggest saving the original books to preserve those editions for people still using older versions of the software. rihowa...@gmail.com linux - the best things in life are free On Oct 6, 2011, at 7:10 PM, Martin Langhoff wrote: On Oct 6, 2011 6:28 PM, Cherry Withers cwith...@ekindling.org wrote: Could you please shed a light on which manuals in FlossManuals make up the Help Activity? Some of us who will be jumping in to refresh it don't know much about the history. To be honest, I don't really know. Here's what I know: - open the help activity - look at the left-panel navigation TOC - open the Sugar manual -- you'll see lots of topics aren't there! So the topics that aren't there are in general from manuals about a specific activity. There is also a flossmanual about the XO itself -- I think some chapters from there have been included. On flossmanuals, there is an option to make a book or something like that. When you do that, it lets you pick and order chapters from many manuals. Perhaps that's what's been done -- perhaps the mix was prepared on the flossmanuals website. It is trivial to see if you look at both the Help activity and the stuff on flossmanuals. cheers, m ___ Sugar-devel mailing list sugar-de...@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
Thanks Martin! Unless they're named differently or have another version in a different name, here's what I can find when I do a search on All Manuals: XO manual (Introduction, Getting Started, Battery, Network, Support, Appendices): http://booki.flossmanuals.net/xo/_draft/ Browse Activity Chapter: http://booki.flossmanuals.net/browse/_draft/_v/1.0/ Write Activity Chapter: http://booki.flossmanuals.net/write-activity/_draft/: Record Activity Chapter: http://booki.flossmanuals.net/record/_draft/ Turtle Art Activity Chapter: http://booki.flossmanuals.net/turtle-art/_draft/ Sugar (What is Sugar section, Interface Chapter, Activities Chapter) : http://booki.flossmanuals.net/sugar/_draft/ There are other incomplete activity chapters already set up in FlossManual. ---Cherry Sounds about right? ---Cherry On Thu, Oct 6, 2011 at 7:10 PM, Martin Langhoff martin.langh...@gmail.comwrote: On Oct 6, 2011 6:28 PM, Cherry Withers cwith...@ekindling.org wrote: Could you please shed a light on which manuals in FlossManuals make up the Help Activity? Some of us who will be jumping in to refresh it don't know much about the history. To be honest, I don't really know. Here's what I know: - open the help activity - look at the left-panel navigation TOC - open the Sugar manual -- you'll see lots of topics aren't there! So the topics that aren't there are in general from manuals about a specific activity. There is also a flossmanual about the XO itself -- I think some chapters from there have been included. On flossmanuals, there is an option to make a book or something like that. When you do that, it lets you pick and order chapters from many manuals. Perhaps that's what's been done -- perhaps the mix was prepared on the flossmanuals website. It is trivial to see if you look at both the Help activity and the stuff on flossmanuals. cheers, m ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
On Wed, Oct 5, 2011 at 7:20 AM, Chris Leonard cjlhomeaddr...@gmail.comwrote: On Wed, Oct 5, 2011 at 1:12 AM, Chris Leonard cjlhomeaddr...@gmail.com wrote: On Tue, Oct 4, 2011 at 7:19 PM, Martin Langhoff martin.langh...@gmail.com wrote: On Tue, Oct 4, 2011 at 6:25 PM, Chris Leonard cjlhomeaddr...@gmail.com wrote: In any refresh of the XO manual (Help Activity), I would very much appreciate if some structural choices could be made to facilitate the internationalization of the text Agreed on the general goal. My understanding is that the Help activity is assembled from content from several manuals about sugar and activities, created and edited at FLOSS Manuals. I suspect that FLOSS Manuals has a means to maintain translated versions, not sure how well it works, but several existing manuals offer alternative language versions. Maybe the FLOSS manuals platforms is terminally borked in this regard, I honestly hope not. Because Pootle is not suited for this style of documentation -- we sure want something wiki-ish that handles paragraphs, tables, embedded images... (earlier message sent prematurely) I need to spend a little bit of time on FLOSSManuals, I'd heard something about hem incorporating booki http://www.booki.cc/ but I have not investigated it extensively since then to see how much of an improvement it is with regards to L10n. L10n of long-form content is an area where I think there are some excellent bits and pieces, but I'm not convinced that there is a really nice end-to-end solution yet. I think very highly of FLOSSManuals as a book publishing platform, but was less than impressed with it's L10n workflow. I am happy that several of the Sugar OLPC boks have been translated, but these have been time-focused efforts requiring a lot of coordination and not amenable to the slower accumulation of collaborative work that characterizes Poolte L10n work. I like also wikislicing as a content collection method and Wikimedia's WikiBook effort has some superb features with respect to content collection and publishing. To the extent that orthologous articles exist across wikis it can also address L10n, essentially by slicing pre-localized content. Unfortunately, while the PDF output from WikiBooks is quite beautifully formatted, it's size is large and PDFs are not that easy to edit after the fact. http://wiki.laptop.org/go/File:TamTamSuite_collection.pdf The ,odt output option from WikiBooks is easier to edit, but I think it has real deficiencies in formatting, and IMHO, is frankly ugly. However, both of these formats produce rather large files compared to simple HTML and an HTML output option is not currently available. My reasoning on requesting availability of a plain text version is that facilitates bringing the strings to the localizer, instead of forcing you to bring the localizer to the strings (and a new tool). Admittedly, this has its; own flaws and requires more substantial post-processing to get a nicely formatted product. The ideal all-singing, all-dancing long-form L10n tool with content management system features and e-publishing features may be out there, but I haven't seen it yet. I do welcome others to join in the exploration of the various options and techniques for cobbling together a workflow that optimally meets our needs, but most of all, I encourage thinking about i18n / L10n in all aspects of our work. Cjl, thanks a lot for reminding us about the importance of localization:-) Samy from France was kind enough to collect some links and information for translation tools in another thread (Open translation tools) and I hope to have some time to look at them in some detail before I head to San Francisco. Maybe what we should try to do is try to compile some sort of good practice guide for translation of documentation (as opposed to software itself) for these types of events... Cheers, Christoph -- Christoph Derndorfer editor, OLPC News [www.olpcnews.com] volunteer, OLPC (Austria) [www.olpc.at] e-mail: christ...@derndorfer.eu ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
On Wed, Oct 5, 2011 at 1:12 AM, Chris Leonard cjlhomeaddr...@gmail.com wrote: L10n of long-form content is an area where I think there are some excellent bits and pieces, but I'm not convinced that there is a really nice end-to-end solution yet. I think very highly of FLOSSManuals as a book publishing platform, but was less than impressed with it's L10n workflow. AFAIK FLOSSManuals software infra is being worked on, and that involves (at least in part) Douglas Bagnall who used to work with OLPC on the School Server. I am happy that several of the Sugar OLPC boks have been translated, but these have been time-focused efforts requiring a lot of coordination and not amenable to the slower accumulation of collaborative work that characterizes Poolte L10n work. Well... for translating something long-form, I do think you need an initial focussed translation effort, perhaps followed by piecemeal maintenance. Prose style and cohesion do need that initial translation to be done by one person or a small well coordinated group. I agree with all your other points :-) m -- martin.langh...@gmail.com 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
Re: [Sugar-devel] Potential volunteer offering technical writing
On Wed, Oct 5, 2011 at 9:41 AM, Martin Langhoff martin.langh...@gmail.com wrote: On Wed, Oct 5, 2011 at 1:12 AM, Chris Leonard cjlhomeaddr...@gmail.com wrote: L10n of long-form content is an area where I think there are some excellent bits and pieces, but I'm not convinced that there is a really nice end-to-end solution yet. I think very highly of FLOSSManuals as a book publishing platform, but was less than impressed with it's L10n workflow. AFAIK FLOSSManuals software infra is being worked on, and that involves (at least in part) Douglas Bagnall who used to work with OLPC on the School Server. By no means should my *critique* of FLOSSManuals L10n be taken for *criticism* of FLOSSManuals, As both a community and a tool, they have been very good to Sugar / OLPC. The collaboration with them has been valuable and productive and perhaps we can build on that relationship to work with them to improve their L10n tools as they do such an excellent job in other important areas of long-form content creation and sharing. I admit that I do need to look at their tools with a fresh eye, as it has been some time since I have thoroughly investigated the L10n workflow. As for the use of FLOSSManuals as the source and L10n workflow for the Help Activity, sadly, I think the more pressing challenge may be the lack of documentation of the process employed by Seth and his collaborators in the original Help Activity creation from FLOSSManual sources. I'm simply not sure that I would know exactly how to go about taking a refreshed set of FLOSSManual chapters and convert it into a revised Help Activity. Better documentation of documentation creation is a very meta concept, but I know from my time in a heavily regulated industry (pharma) that SOP #1 is always the SOP on creating SOPs. I am happy that several of the Sugar OLPC books have been translated, but these have been time-focused efforts requiring a lot of coordination and not amenable to the slower accumulation of collaborative work that characterizes Poolte L10n work. Well... for translating something long-form, I do think you need an initial focussed translation effort, perhaps followed by piecemeal maintenance. Prose style and cohesion do need that initial translation to be done by one person or a small well coordinated group. I completely agree that translation sprints are an important aspect of content creation, but have some lingering concerns about the ultra-marathon of maintaining L10n over time and versions. Another non-technical aspect is the difficulty in creating such focused periods of effort to tackle a large project within multiple language communities. We do fairly well with gathering small quanta of discontinuous effort that accumulate over time in Pootle (it is a bit like the advantages that developers see in the distributed nature of git as a source code repo), but it is a much greater challenge to organize concerted efforts by a language team. In any event, I am happy just to be having a conversation about the challenges and to see people thinking carefully about the i18n / L10n process. There may be no single ideal solution simply waiting for us, but it is only by considering the issues and options that will we move towards better and more reproducible processes. Warmest Regards, cjl ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
On Wed, Oct 5, 2011 at 10:28 AM, Chris Leonard cjlhomeaddr...@gmail.com wrote: AFAIK FLOSSManuals software infra is being worked on, and that ... By no means should my *critique* of FLOSSManuals L10n be taken for *criticism* of FLOSSManuals, As both a community and a tool, they Oh, all I meant is that maybe they are working on it, or about to work on making it better. lack of documentation of the process employed by Seth and his collaborators in the original Help Activity creation from FLOSSManual sources. I'm simply not sure that I would know exactly how to go about taking a refreshed set of FLOSSManual chapters and convert it into a revised Help Activity. Same here, but to be honest I haven't searched, so maybe it's written and I am perfectly ignorant. Maybe there are notes somewhere? In the git repo? Has anyone searched? Anyone asked Seth and co? Again, I agree on your other points - cheers, m -- martin.langh...@gmail.com 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
Re: [Sugar-devel] Potential volunteer offering technical writing
As for the use of FLOSSManuals as the source and L10n workflow for the Help Activity, sadly, I think the more pressing challenge may be the lack of documentation of the process employed by Seth and his collaborators in the original Help Activity creation from FLOSSManual sources. I am not worried about that. The help activity is only a modified Browse activity with a lot of html files in a directory. I think there are different tasks and will be done by different people at different times: * Create a updated version of the documentation in Floss manuals. * Update the help activity * Translate the manuals (like we did with 'Make your own Sugar Activities') Would be good if the new manuals are cloned and we can keep the old ones to the users using the old version of Sugar Gonzalo. ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
On Wed, Oct 5, 2011 at 12:13 PM, Gonzalo Odiard gonz...@laptop.org wrote: As for the use of FLOSSManuals as the source and L10n workflow for the Help Activity, sadly, I think the more pressing challenge may be the lack of documentation of the process employed by Seth and his collaborators in the original Help Activity creation from FLOSSManual sources. I am not worried about that. Well, yes and no :-) The help activity is only a modified Browse activity with a lot of html files in a directory. I think there are different tasks and will be done by different people at different times: * Create a updated version of the documentation in Floss manuals. Yes * Update the help activity Right, here I am not sure if you have seen: the current Help activity is a combination of several floss manuals mixed together. And it looks like it may have some tweaks and customizations. * Translate the manuals (like we did with 'Make your own Sugar Activities') Yep, though I think on this track we all agree that you'd really make a different activity for each language... Would be good if the new manuals are cloned and we can keep the old ones to the users using the old version of Sugar +10 on this. Some Sugar versions are widely used... m -- martin.langh...@gmail.com 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
Re: [Sugar-devel] Potential volunteer offering technical writing
Right, here I am not sure if you have seen: the current Help activity is a combination of several floss manuals mixed together. And it looks like it may have some tweaks and customizations. Quoting a contemporary thinker we can use a directory capable filesystem :) Gonzalo ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
On Wed, Oct 5, 2011 at 12:50 PM, Gonzalo Odiard gonz...@laptop.org wrote: Right, here I am not sure if you have seen: the current Help activity is a combination of several floss manuals mixed together. And it looks like it may have some tweaks and customizations. Quoting a contemporary thinker we can use a directory capable filesystem Hmm, say you have a few translations. Say you have /screenshots/ in the different languages. I like directory-capable filesystems, but they suck at the infinite-storage thing... m -- martin.langh...@gmail.com 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
Re: [Sugar-devel] Potential volunteer offering technical writing
On Wed, Oct 5, 2011 at 1:52 PM, Martin Langhoff martin.langh...@gmail.comwrote: On Wed, Oct 5, 2011 at 12:50 PM, Gonzalo Odiard gonz...@laptop.org wrote: Right, here I am not sure if you have seen: the current Help activity is a combination of several floss manuals mixed together. And it looks like it may have some tweaks and customizations. Quoting a contemporary thinker we can use a directory capable filesystem Hmm, say you have a few translations. Say you have /screenshots/ in the different languages. We do not have translations in Help Activity. And is not a good idea use the same tools/strategies to translate a few strings in a activity and a full text document. Include multiple languages in the Help activity does not scale. We can use get-books/pathagar to resolve the multiple languages and the infinite storage problem. I think the first problem is have the updated manuals, and can be done in a few days by a group of volunteers. Gonzalo I like directory-capable filesystems, but they suck at the infinite-storage thing... m -- martin.langh...@gmail.com 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
Re: Potential volunteer offering technical writing
On Tue, Oct 4, 2011 at 5:18 AM, Martin Langhoff martin.langh...@gmail.comwrote: Hi Tabs! that's great! Here's an idea: I was looking at recently at the FLOSS Manuals manuals for Sugar and activities... and they are a bit dated -- they cover Sugar 0.86 or so. Screens have changed quite a bit :-) and some procedures are much simpler (ad hoc networking for example). And the FLOSS Manuals feed into the Help Activity, so work there pays of many times over... My 2 deflationary cents... +2 equally deflationary Eurocents;-) eKindling's Cherry (now in CC) suggested a similar Help Activity Refresh as one of the activities for the OLPC-SF Community Summit and some good ideas were thrown around as a result. So I think it makes sense to tie those two thread of conversation together. Cheers, Christoph m On Fri, Sep 30, 2011 at 5:51 AM, Tabitha Roder tabi...@tabitha.net.nz wrote: Hi If we had a volunteer (English Native language) professional technical writer, what writing would be of most use to OLPC or Sugar that we can point her in the direction of? She currently works with developers to write end user documentation. Thanks Tabitha - NZ volunteers ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel -- martin.langh...@gmail.com 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 -- Christoph Derndorfer editor, OLPC News [www.olpcnews.com] volunteer, OLPC (Austria) [www.olpc.at] e-mail: christ...@derndorfer.eu ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
All, In any refresh of the XO manual (Help Activity), I would very much appreciate if some structural choices could be made to facilitate the internationalization of the text so that it can be converted into PO files and posted on Pootle for translation into a renewed Help Activity. That is not to say a pretty web-version would not also be nice. An ideal format option would include producing a simple plain text version with paragraphs separated by a whitespace line (easily parsed by txt2po) and back converted with po2txt. I have had very little success with the html2po tool from the Translate Toolkit when I explored parsing the current Help Activity's html pages for i18n and L10n. Nor have I had any great success with parsing the FLOSSManuals version. On the other hand, txt2po and po2txt has been working well for the Waveplace lesson plans. I have long considered it a great shame that the Help Activity was only in English, and although the XO manual on FLOSSManuals has seen translation into a few languages, I fear that the tools for long-form content L10n are just not as functional as Pootle or as well used by our L10n community. cjl On Tue, Oct 4, 2011 at 9:12 AM, Christoph Derndorfer christoph.derndor...@gmail.com wrote: On Tue, Oct 4, 2011 at 5:18 AM, Martin Langhoff martin.langh...@gmail.com wrote: Hi Tabs! that's great! Here's an idea: I was looking at recently at the FLOSS Manuals manuals for Sugar and activities... and they are a bit dated -- they cover Sugar 0.86 or so. Screens have changed quite a bit :-) and some procedures are much simpler (ad hoc networking for example). And the FLOSS Manuals feed into the Help Activity, so work there pays of many times over... My 2 deflationary cents... +2 equally deflationary Eurocents;-) eKindling's Cherry (now in CC) suggested a similar Help Activity Refresh as one of the activities for the OLPC-SF Community Summit and some good ideas were thrown around as a result. So I think it makes sense to tie those two thread of conversation together. Cheers, Christoph m On Fri, Sep 30, 2011 at 5:51 AM, Tabitha Roder tabi...@tabitha.net.nz wrote: Hi If we had a volunteer (English Native language) professional technical writer, what writing would be of most use to OLPC or Sugar that we can point her in the direction of? She currently works with developers to write end user documentation. Thanks Tabitha - NZ volunteers ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel -- martin.langh...@gmail.com 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 -- Christoph Derndorfer editor, OLPC News [www.olpcnews.com] volunteer, OLPC (Austria) [www.olpc.at] e-mail: christ...@derndorfer.eu ___ Sugar-devel mailing list sugar-de...@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
On Tue, Oct 4, 2011 at 6:25 PM, Chris Leonard cjlhomeaddr...@gmail.com wrote: In any refresh of the XO manual (Help Activity), I would very much appreciate if some structural choices could be made to facilitate the internationalization of the text Agreed on the general goal. My understanding is that the Help activity is assembled from content from several manuals about sugar and activities, created and edited at FLOSS Manuals. I suspect that FLOSS Manuals has a means to maintain translated versions, not sure how well it works, but several existing manuals offer alternative language versions. Maybe the FLOSS manuals platforms is terminally borked in this regard, I honestly hope not. Because Pootle is not suited for this style of documentation -- we sure want something wiki-ish that handles paragraphs, tables, embedded images... cheers, m -- martin.langh...@gmail.com 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
Re: [Sugar-devel] Potential volunteer offering technical writing
On Tue, Oct 4, 2011 at 7:19 PM, Martin Langhoff martin.langh...@gmail.com wrote: On Tue, Oct 4, 2011 at 6:25 PM, Chris Leonard cjlhomeaddr...@gmail.com wrote: In any refresh of the XO manual (Help Activity), I would very much appreciate if some structural choices could be made to facilitate the internationalization of the text Agreed on the general goal. My understanding is that the Help activity is assembled from content from several manuals about sugar and activities, created and edited at FLOSS Manuals. I suspect that FLOSS Manuals has a means to maintain translated versions, not sure how well it works, but several existing manuals offer alternative language versions. Maybe the FLOSS manuals platforms is terminally borked in this regard, I honestly hope not. Because Pootle is not suited for this style of documentation -- we sure want something wiki-ish that handles paragraphs, tables, embedded images... Last I checked, the FLOSS Manual i18n system was very awkward to use. There are some XML-based i18n systems I looked at when we were first getting started, but it seems that PO files still are the way to go. regards. -walter cheers, m -- martin.langh...@gmail.com 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 ___ Sugar-devel mailing list sugar-de...@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel -- Walter Bender Sugar Labs http://www.sugarlabs.org ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
I think the easier way is have a different floss manual by language. The Help Activity is only a shell, we can create a e-pub or a content bundle if we want, but doing the i18n at this level will be a nightmare. Gonzalo On Tue, Oct 4, 2011 at 7:25 PM, Chris Leonard cjlhomeaddr...@gmail.comwrote: All, In any refresh of the XO manual (Help Activity), I would very much appreciate if some structural choices could be made to facilitate the internationalization of the text so that it can be converted into PO files and posted on Pootle for translation into a renewed Help Activity. That is not to say a pretty web-version would not also be nice. An ideal format option would include producing a simple plain text version with paragraphs separated by a whitespace line (easily parsed by txt2po) and back converted with po2txt. I have had very little success with the html2po tool from the Translate Toolkit when I explored parsing the current Help Activity's html pages for i18n and L10n. Nor have I had any great success with parsing the FLOSSManuals version. On the other hand, txt2po and po2txt has been working well for the Waveplace lesson plans. I have long considered it a great shame that the Help Activity was only in English, and although the XO manual on FLOSSManuals has seen translation into a few languages, I fear that the tools for long-form content L10n are just not as functional as Pootle or as well used by our L10n community. cjl On Tue, Oct 4, 2011 at 9:12 AM, Christoph Derndorfer christoph.derndor...@gmail.com wrote: On Tue, Oct 4, 2011 at 5:18 AM, Martin Langhoff martin.langh...@gmail.com wrote: Hi Tabs! that's great! Here's an idea: I was looking at recently at the FLOSS Manuals manuals for Sugar and activities... and they are a bit dated -- they cover Sugar 0.86 or so. Screens have changed quite a bit :-) and some procedures are much simpler (ad hoc networking for example). And the FLOSS Manuals feed into the Help Activity, so work there pays of many times over... My 2 deflationary cents... +2 equally deflationary Eurocents;-) eKindling's Cherry (now in CC) suggested a similar Help Activity Refresh as one of the activities for the OLPC-SF Community Summit and some good ideas were thrown around as a result. So I think it makes sense to tie those two thread of conversation together. Cheers, Christoph m On Fri, Sep 30, 2011 at 5:51 AM, Tabitha Roder tabi...@tabitha.net.nz wrote: Hi If we had a volunteer (English Native language) professional technical writer, what writing would be of most use to OLPC or Sugar that we can point her in the direction of? She currently works with developers to write end user documentation. Thanks Tabitha - NZ volunteers ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel -- martin.langh...@gmail.com 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 -- Christoph Derndorfer editor, OLPC News [www.olpcnews.com] volunteer, OLPC (Austria) [www.olpc.at] e-mail: christ...@derndorfer.eu ___ Sugar-devel mailing list sugar-de...@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel ___ 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: [Sugar-devel] Potential volunteer offering technical writing
On Tue, Oct 4, 2011 at 7:19 PM, Martin Langhoff martin.langh...@gmail.com wrote: On Tue, Oct 4, 2011 at 6:25 PM, Chris Leonard cjlhomeaddr...@gmail.com wrote: In any refresh of the XO manual (Help Activity), I would very much appreciate if some structural choices could be made to facilitate the internationalization of the text Agreed on the general goal. My understanding is that the Help activity is assembled from content from several manuals about sugar and activities, created and edited at FLOSS Manuals. I suspect that FLOSS Manuals has a means to maintain translated versions, not sure how well it works, but several existing manuals offer alternative language versions. Maybe the FLOSS manuals platforms is terminally borked in this regard, I honestly hope not. Because Pootle is not suited for this style of documentation -- we sure want something wiki-ish that handles paragraphs, tables, embedded images... I need to spend a little bit of time on FLOSSManuals, I'd heard something about hem incorporating booki http://www.booki.cc/ but I have not investigated it extensively since then to see how much of an improvement it is with regards to L10n. L10n of long-form content is an area where I think there are some excellent bits and pieces, but I'm not convinced that there is a really nice end-to-end solution yet. I think very highly of FLOSSManuals as a book publishing platform, but was less than impressed with it's L10n workflow. I am happy that several of the Sugar OLPC boks have been translated, but these have been time-focused efforts requiring a lot of coordination and not amenable to the slower accumulation of collaborative work that characterizes Poolte L10n work. I like also wikislicing as a content collection method and Wikimedia's WikiBook effort has some superb features with respect to content collection and publishing. To the extent that orthologous articles exist across wikis it can also address L10n, essentially by slicing pre-localized content. Unfortunately, while the PDF output from WikiBooks is quite beautifully formatted, it's size is large and PDFs are not that easy to edit after the fact. http://wiki.laptop.org/go/File:TamTamSuite_collection.pdf The ,odt output option from WikiBooks is easier to edit, but I think it has real deficiencies in formatting, and IMHO, is frankly ugly. However, both of these formats produce rather large files compared to simple HTML and an HTML output option is not currently available. My reasoning on requesting availability fo a plain text version is tha tit facilitates bringing the strings to the locali ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: [Sugar-devel] Potential volunteer offering technical writing
On Wed, Oct 5, 2011 at 1:12 AM, Chris Leonard cjlhomeaddr...@gmail.com wrote: On Tue, Oct 4, 2011 at 7:19 PM, Martin Langhoff martin.langh...@gmail.com wrote: On Tue, Oct 4, 2011 at 6:25 PM, Chris Leonard cjlhomeaddr...@gmail.com wrote: In any refresh of the XO manual (Help Activity), I would very much appreciate if some structural choices could be made to facilitate the internationalization of the text Agreed on the general goal. My understanding is that the Help activity is assembled from content from several manuals about sugar and activities, created and edited at FLOSS Manuals. I suspect that FLOSS Manuals has a means to maintain translated versions, not sure how well it works, but several existing manuals offer alternative language versions. Maybe the FLOSS manuals platforms is terminally borked in this regard, I honestly hope not. Because Pootle is not suited for this style of documentation -- we sure want something wiki-ish that handles paragraphs, tables, embedded images... (earlier message sent prematurely) I need to spend a little bit of time on FLOSSManuals, I'd heard something about hem incorporating booki http://www.booki.cc/ but I have not investigated it extensively since then to see how much of an improvement it is with regards to L10n. L10n of long-form content is an area where I think there are some excellent bits and pieces, but I'm not convinced that there is a really nice end-to-end solution yet. I think very highly of FLOSSManuals as a book publishing platform, but was less than impressed with it's L10n workflow. I am happy that several of the Sugar OLPC boks have been translated, but these have been time-focused efforts requiring a lot of coordination and not amenable to the slower accumulation of collaborative work that characterizes Poolte L10n work. I like also wikislicing as a content collection method and Wikimedia's WikiBook effort has some superb features with respect to content collection and publishing. To the extent that orthologous articles exist across wikis it can also address L10n, essentially by slicing pre-localized content. Unfortunately, while the PDF output from WikiBooks is quite beautifully formatted, it's size is large and PDFs are not that easy to edit after the fact. http://wiki.laptop.org/go/File:TamTamSuite_collection.pdf The ,odt output option from WikiBooks is easier to edit, but I think it has real deficiencies in formatting, and IMHO, is frankly ugly. However, both of these formats produce rather large files compared to simple HTML and an HTML output option is not currently available. My reasoning on requesting availability of a plain text version is that facilitates bringing the strings to the localizer, instead of forcing you to bring the localizer to the strings (and a new tool). Admittedly, this has its; own flaws and requires more substantial post-processing to get a nicely formatted product. The ideal all-singing, all-dancing long-form L10n tool with content management system features and e-publishing features may be out there, but I haven't seen it yet. I do welcome others to join in the exploration of the various options and techniques for cobbling together a workflow that optimally meets our needs, but most of all, I encourage thinking about i18n / L10n in all aspects of our work. cjl ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel
Re: Potential volunteer offering technical writing
Hi Tabs! that's great! Here's an idea: I was looking at recently at the FLOSS Manuals manuals for Sugar and activities... and they are a bit dated -- they cover Sugar 0.86 or so. Screens have changed quite a bit :-) and some procedures are much simpler (ad hoc networking for example). And the FLOSS Manuals feed into the Help Activity, so work there pays of many times over... My 2 deflationary cents... m On Fri, Sep 30, 2011 at 5:51 AM, Tabitha Roder tabi...@tabitha.net.nz wrote: Hi If we had a volunteer (English Native language) professional technical writer, what writing would be of most use to OLPC or Sugar that we can point her in the direction of? She currently works with developers to write end user documentation. Thanks Tabitha - NZ volunteers ___ Devel mailing list Devel@lists.laptop.org http://lists.laptop.org/listinfo/devel -- martin.langh...@gmail.com 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
