[FM Discuss] style guide start for OLPC/Sugar

[Seth Woodworth]

Comments in line:


> -         You do use both the XO and the XO laptop. For simplicity, you
> could probably just use the XO in most cases.

Let's stay away from 'laptop' with out qualification.  In Demos I only call
it a 'laptop' inside of an explanation of what the XO is and isn't.  Calling
it a laptop has certain connotations (Microsoft, Spread sheets, office etc)
and *not* calling it a laptop gives different connotations (that it's merely
a game, leapfrog, etc).

> -         After first using portable USB storage device, use USB device.
> Don't use USB stick.

Maybe we should look at translatability (real word?) before we make a
decision on this one.

> -         Use consistent capitalization when talking about XO Activities.
I
> suggest capitalizing it, which you do most often.

If we can decide on this, I'm willing to make the change on the wiki as
well.  First instance in a page should be [[ ]]'d too.


> -         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.

I second this idea.

> -         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.

If we are speaking about Network, we might choose Mesh as a verb instead.
Activities are supposed to be all verbs and 'Meshing' is an integral part of
an activity?  Give me some examples and I can run it by more people at the
office.


> Put punctuation outside the quoted material.

I prefer to put punctuation outside of quotes.  This makes more sense to me
from a programming standpoint.



> When in doubt, refer to Read Me First! A Style Guide for the Computer
> Industry, by Sun Technical Publications.

I'll get a copy for the office!

> Let me know if this guide matches what you had in mind, and where it could
> be housed.

Once it's produced at FM I think that we should mirror it or link to it in
several places.  It would be great to be more consistent in other
documentation.


Seth
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20080710/46bb9069/attachment-0001.htm>