Hi-- Here are the main topics I'm proposing for our editorial cheatsheet for OpenSolaris docs. I've included subtopics where I've fleshed out some ideas. My strategy is to offer guidance about the most obvious things that stand out when style is inconsistent.
We've discussed having a length of 1-5 pages for this cheatsheet. Based on what I'm proposing, I think we're looking at 5 pages. However, I'm wondering if folks would consider going up to 8 pages. Jean McVey, a colleague of mine at Sun, has greatly condensed the Procedures chapter in the internal Sun Editorial Style Guide from 24 pages to 3. If you'd like succinct but surprisingly complete guidelines about writing procedures, I'd recommend adding these 3 pages to our cheatsheet. I'm thinking that a Phase 2 project could be to develop guidelines for wikis and blogs. That would be completely new content (and perhaps a separate document), whereas what I'm proposing below is mostly derived from existing content in the Documentation Style Guide for OpenSolaris. I'm wondering if this cheatsheet might also be a useful tool for the OpenSolaris web site overall. Thoughts? I'll be out of town June 19-23 without email access. Thanks for your feedback. Alysson === 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 (content depends on length available) 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) This message posted from opensolaris.org
