[prev in list] [next in list] [prev in thread] [next in thread] 

List:       opensolaris-docs-discuss
Subject:    [docs-discuss] editorial cheatsheet for OpenSolaris docs
From:       Alysson Troffer <alysson.troffer () sun ! com>
Date:       2008-06-17 14:20:51
Message-ID: 29705685.1213737928003.JavaMail.Twebapp () oss-app1
[Download RAW message or body]

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
_______________________________________________
docs-discuss mailing list
docs-discuss@opensolaris.org


[prev in list] [next in list] [prev in thread] [next in thread]