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
