Hi Cathleen, Thanks for finding those nits and for your suggestions. Of course, the indenting was perfect when I tested the cheat sheet in my browser before putting the HTML on opensolaris.org. :-)
I agree with everything and will make changes accordingly. Cheers, Alysson Cathleen Reiher wrote: > Hi Alysson, > > The editorial cheat sheet is terrific! > I really like the content you included > in this guide. > > I found a few nits: > > - GUI Tips > > - First list item, change "as the appear" > to "as they appear" > > - Procedure Writing Tips > > - Correct example indenting funny in > the "Place any explanatory text in a > separate paragraph under the step > text" list item; text should be indented > under the step, not outdented. The > text should be aligned with the step > paragraph text and not the step > number. > > - Correct example indenting funny in > the first "Write meaningful steps" > item. Explanatory text should align > with step text, not step number. > > - In "Explain to readers why...skip," > indent the step bullet list. > > - In second list item of "step branching," > indent the step bullet list. > > - Common Term Usage and Style > > - file name: should we mention that > it is "filename" when used as a > variable name (same for user name, > path name, and host name, I believe) > > - OpenSolaris: Should we mention > which nouns should be used with > OpenSolaris since it's a trademarked > term? > > Thanks for creating this document, Alysson. > > Cathleen. > > Alysson Troffer wrote: >> 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 >> _______________________________________________ >> docs-discuss mailing list >> docs-discuss at opensolaris.org -- This message posted from opensolaris.org
