Hi Folks, I'll assume that silence equals assent and will move forward with the topics listed below for the cheatsheet. I'll be on vacation July 8-14 and will start working on a draft after I return.
Cheers, Alysson > 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
