[FM Discuss] style guide start for OLPC/Sugar
Anne Gentle
annegentle at gmail.com
Wed Jul 9 20:44:42 PDT 2008
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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20080709/af53a30e/attachment.htm>
More information about the Discuss
mailing list