[FM Discuss] style guide start for OLPC/Sugar
Adam Floss
adam at flossmanuals.net
Wed Jul 9 20:58:50 PDT 2008
Inkscape manual on FM has its own style guide linked from FM. I will
set this facility up for all new manuals and send link
Adam
This is probably sent while in transit
On Jul 10, 2008, at 5:44, "Anne Gentle" <annegentle at gmail.com> wrote:
> Hi Joshua,
> Not sure where to put this but it can get outta my email and into
> the wiki somewhere. Here are the guidelines my professional editor
> gave me while she reviewed the OLPC manual:
>
> General terminology observations:
>
> - You do use both the XO and the XO laptop. For simplicity,
> you could probably just use the XO in most cases.
> - After first using portable USB storage device, use USB
> device. Don't use USB stick.
> - Use consistent capitalization when talking about XO
> Activities. I suggest capitalizing it, which you do most often.
> - Don't use view and page interchangeably. Use view to refer
> to the different XO interface. Use page when you are sending the
> users out to the Internet (as in web page). Also, use a consistent
> capitalization for view. You might want to capitalize it, like you
> do Activities.
> - I would suggest using a consistent verb, click, for
> telling the users what to do with their pointer on the screen. Don't
> use choose or select.
> - You might consider creating a glossary for the book. It
> would be a good start for a translation glossary. I would include
> USB storage device, Activity, View, network, mesh network, Give 1
> Get 1 (G1 G1), antennae.
> - Use network only as a noun and adjective, not as a verb
> (one rule of writing for translation is to use a word as only one
> part of speech; you would especially not want to use a word as both
> a noun and a verb).
>
> As for overarching style that Floss could adopt, I like simplicity.
> Write well, quickly, in the active voice and the present tense.
>
> Put punctuation outside the quoted material.
>
> Place periods at the end of bulleted list items.
> Replace semicolons with periods.
>
> Use numerals for all numbers below ten. For numbers above ten, spell
> out the number.
>
> When in doubt, refer to Read Me First! A Style Guide for the
> Computer Industry, by Sun Technical Publications.
> Let me know if this guide matches what you had in mind, and where it
> could be housed.
> Thanks,
> Anne
>
>
> On Wed, Jul 9, 2008 at 3:59 PM, adam hyde <adam at flossmanuals.net>
> wrote:
> hi,
>
> > 1) We should have a suggested style-guide page on flossmanuals. This
> > project would be a good opportunity for us to start adding to that.
> > The rule of copyediting isn't "correctness" but "consistency." I'd
> be
> > happy to help in style guide development as I have experience in
> doing
> > this.
>
> This would be wonderful. Would you feel like taking the lead in
> getting
> this style guide together? I am sure Anne has some ideas on it already
> also.
>
>
> >
> > 2) I would suggest we have a project lead/Editor that helps to
> > determine if we've met the necessary goals we want to reach in a
> > timely manner. Not a dicator, but someone who can help steer help
> > toward things that are most in need of being finished. Specifically,
> > it would be good if we could mark pages/sections as "needs
> rewriting,"
> > "needs copy-editing," "needs graphic," etc. A good way to
> > annotate/bug-track.
>
> We are almost finished with a basic status marker for workflow
> management of chapters. Should be ready tomorrow.
>
> >
> > 3) It would be good to have the option of going to print. To do
> that,
> > there are a number of print-quality requirements, such as picture
> DPI
> > and other things. We should have a list of technical requirements
> > needed to allow for that option in the future.
> >
>
> We have a beta system in place for producing print ready source for
> print on demand. I will send a url when its ready for a peak. It
> utilises CSS3 for formatting print ready book source from FM...the
> final
> result looks beautiful. if you are dying for a look at the beta I am
> happy to send anyone a preview url.
>
> adam
>
>
>
> > -Josh
> >
> > On Wed, Jul 9, 2008 at 12:34 AM, Brian Jordan <brian at laptop.org>
> > wrote:
> > On Tue, Jul 8, 2008 at 7:08 AM, Christoph Derndorfer
> > <e0425826 at student.tuwien.ac.at> wrote:
> > > Greg Dekoenigsberg schrieb:
> > >>
> > >> On Tue, 8 Jul 2008, Walter Bender wrote:
> > >>
> > >>> I can participate if it is in the second-half of
> August...
> > I have lots
> > >>> more material from when I made the "getting started"
> guide
> > sitting on
> > >>> the "cutting room floor".
> > >>
> > >> I think it's worth considering making this and pitching
> it
> > to O'Reilly. In
> > >> the same format as Karl Fogel's "Producing Open Source
> > Software" and other
> > >> works: available for sale, but freely licensed.
> > >>
> > >> The creation of a physical artifact that can be purchased
> > in stores is "a
> > >> big deal" and would go a long way towards establishing
> > credibility and
> > >> permanence. "Holy crap, Sugar must be for real --
> they're
> > selling the book
> > >> in Barnes and Noble! With a Live CD!"
> > >
> > > That's an excellent idea and I think it would be great to
> > make a Live-CD and
> > > Sugar documentation available to the masses! :-)
> >
> >
> > This is a fantastic idea. A publication with step by step
> > activity
> > creation instructions and a liveCD with the barebones
> > activities
> > (templates?) referenced in the publication would provide a
> > distinct
> > starting point for developers interested in our project,
> even
> > those
> > who don't have an XO yet.
> >
> > I'd be more than willing to help with pyGame/OLPCGames
> > instructions/templates--I've been working through this
> sort of
> > activity creation process all summer.
> >
> > Cheers,
> > Brian
> >
> >
> > >>
> > >> "Make no small plans." Daniel Burnham. :)
> > >>
> > >> --g
> > >> _______________________________________________
> > >> Its.an.education.project mailing list
> > >> Its.an.education.project at lists.lo-res.org
> > >>
> > http://lists.lo-res.org/mailman/listinfo/its.an.education.project
> > >>
> > >
> > > --
> > > Christoph Derndorfer
> > > Co-Editor
> > > OLPCnews, http://www.olpcnews.com
> > >
> > > _______________________________________________
> > > Its.an.education.project mailing list
> > > Its.an.education.project at lists.lo-res.org
> > >
> > http://lists.lo-res.org/mailman/listinfo/its.an.education.project
> > >
> >
> >
> >
> >
> > --
> > Joshua Gay
> > [m: 617.966.9792 irc: jgay twitter: joshuagay]
> > Free Software Foundation, campaigns manager
> > [http://fsf.org http://defectivebydesign.org http://badvista.fsf.org
> > http://playogg.org]
> > Textbook Revolution, editor/(re)designer
> > [http://216.93.249.195/wiki irc://freenode.net/#textbookrevolution]
> > One Laptop per Child, volunteer
> > [http://wiki.laptop.org/go/Participate
> > irc://freenode.net/#olpc-content]
> > League of Technical Voters, board of directors
> > [http://www.leagueoftechvoters.org/ -
> > http://transparentfederalbudget.com]
> > Free Textbook Project, lead
> > [http://freetextbookproject.org -- more to come]
> > _______________________________________________
> > Discuss mailing list
> > Discuss at lists.flossmanuals.net
> > http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
> --
> Adam Hyde
> FLOSS Manuals
>
> http://www.flossmanuals.net
> + 31 6 2808 7108
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20080710/e9acae53/attachment-0001.htm>
More information about the Discuss
mailing list