[FM Discuss] style guide start for OLPC/Sugar

[Edward Cherlin]

On Wed, Jul 9, 2008 at 8:44 PM, 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

All of this matches my professional experience. I am particularly
pleased with punctuation outside quotation marks, unless the
punctuation is part of the quotation. Historically punctuation was
placed inside quotation marks because the type for very thin
characters was fragile.
-- 
Edward Cherlin
End Poverty at a Profit by teaching children business
http://www.EarthTreasury.org/
"The best way to predict the future is to invent it."--Alan Kay