Hi folks, I've completed a draft of the OpenSolaris editorial cheat sheet and welcome your feedback. Thanks to Alan McClellan for providing initial feedback on this draft. Thanks to Brendan for originally suggesting the idea to develop this cheat sheet.
The draft is available here: http://opensolaris.org/os/community/documentation/doc_collab/style_guide/editorial_guidelines/ The draft is currently in HTML, though we might want to move it to a wiki, once the new wiki is implemented on opensolaris.org. For now, feel free to send comments in email. (Links to the cheat sheet from our community pages will be added soon.) Some background information follows. Cheers, Alysson === Background Information We decided to develop a cheat sheet to provide guidance for those who just want the basics on editorial style. The main goal is to help promote consistency in OpenSolaris documentation without overwhelming contributors with hundreds of pages of guidelines. The cheat sheet is a few pages longer than the agreed-upon eight pages, but the jump list at the beginning of the document makes the content fairly easy to navigate. The guidelines were derived from the Documentation Style Guide for OpenSolaris and address the following agreed-upon categories: GUI Tips (no bold, common GUI verbs, adding initial caps to field names to make running text clearer, no ellipses, no quotation marks around GUI terms) Headings (guidelines for writing effective headings; capitalizing headings) Lists (introducing lists; capitalizing and punctuating lists) Procedure Writing Tips Pronouns (don't use first-person pronouns, except in blogs; avoid vague and uncertain references between a pronoun and its antecedent; it's vs. its) Punctuation (comma; semicolon; em dash) Referring to Man Pages and URLs Referring to Sun's Trademarked Terms (using as adjectives not nouns or verbs, protecting core Solaris and Java trademarks, not abbreviating terms with a core term in it unless it's also trademarked). Include link to: http://www.sun.com/suntrademarks/ Terminology (common term usage and style--not a glossary; using acronyms and abbreviations; don't use command names as verbs) (Per Rainer, also add a comment about clarity for translation purposes.) -- This message posted from opensolaris.org
