[03/17] docs commit: [CB-3962] rewriting editorial style sheet

[mw...@apache.org]

[CB-3962] rewriting editorial style sheet


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/7803b128
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/7803b128
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/7803b128

Branch: refs/heads/master
Commit: 7803b1280a8b3a0dc7df9b17cbd31736da7b76ac
Parents: 39710f0
Author: Mike Sierra <ms...@adobe.com>
Authored: Fri Nov 1 15:04:35 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Mon Nov 4 11:42:50 2013 -0800

----------------------------------------------------------------------
 STYLESHEET.md | 113 +++++++++++++++++++++++++++++------------------------
 1 file changed, 63 insertions(+), 50 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7803b128/STYLESHEET.md
----------------------------------------------------------------------
diff --git a/STYLESHEET.md b/STYLESHEET.md
index 49da57a..6d7ddfb 100644
--- a/STYLESHEET.md
+++ b/STYLESHEET.md
@@ -83,9 +83,9 @@ immensely.
   scannable items.
 
 * __Procedure Lists__: Don't break out separate procedure items for
-  (1) do this, followed by (2) this describes what just
-  happened. Prefer (1) Do this. It does so-and-so, which you might see
-  in some result. (2) Do that...
+  (1) do this, followed by (2) this describes what just happened.
+  Prefer (1) Do this. It does so-and-so, which you might see in some
+  result. (2) Do that...
 
 * __Topic/Comment Lists__: For bullet lists that provide short topics
   followed by comments, bold the topic, then merge the comment on the
@@ -112,69 +112,48 @@ immensely.
 * __Platform-Specific Notes__ __ios:__ ???
 -->
 
-## In-line Font Formatting
-
-* Use `monospace` for all-purpose nouns used in programming, e.g.: API
-  interfaces, methods, properties, literal values, Unix commands,
-  pathnames, filenames, etc.
-
-* Use __bold__ for on-screen items, such as the names of menu items,
-  buttons, and check boxes.
-
-* Use _italics_ for emphasis, simple mathematical expressions, and
-  variable items (e.g., _x_/_y_ coordinates).
-
-* Do _not_ use ALL CAPS for emphasis. (Exception: in commented code)
-
-* Do _not_ use "quote characters" to deliniate in-line text unless
-  required as part of a value. E.g., not OK to refer to the
-  "text-align" property. OK to set the CSS `text-align` property to
-  `left`, and the `content` property to `"This is some text."`
-  (Exception: within code comments)
-
-* Do not combine in-line formatting such as _`monospace italic`_.
-
 ## Language and Tone
 
 * __Not So Imperitive__: As a rule of thumb, avoid the word "must" and
-  any unnecessarily imperative statements in general.  E.g., instead
-  of "Commands must be run from a cmd or powershell prompt," try "You
-  can run commands either from a cmd or powershell prompt."
+  unnecessarily imperative statements in general.  E.g., instead of
+  "Commands must be run from a cmd or powershell prompt," try "You can
+  run commands either from a cmd or powershell prompt."
 
 * __Avoid the Willies__: Use present tense. "This happens," not "this
   will happen." Future tense comes off as a tenuous prediction. Rule
   of thumb: avoid the word "will."
 
-* Past-tense passive voice is to be avoided. E.g., "the pause event
-  fires when..."  rather than "the pause event is fired when..." Rule
-  of thumb: banish verbs ending in "ed".
-
-* __Action Verbs__: Avoid weak verbs like "is" or "has."
+* __Avoid Passive Voice__: Past-tense passive voice is to be avoided.
+  E.g., "the pause event fires when..."  rather than "the pause event
+  is fired when..." Rule of thumb: banish verbs ending in "ed".
 
-* Avoid noun modification concatenation somnambulation obfuscation.
-  Use your judgement and ask yourself if readers might not actually
-  know what some noun phrase means. If so, explain the actual concept
-  it represents, in this case: "Avoid stringing nouns together into
-  long phrases that come off as impenetrable shop talk that puts
-  everybody to sleep."
+* __Not Kidding, Use Present Tense__: Minimize verbs ending with
+  "ing": "This is necessary to provide...", not "This is necessary for
+  providing..."
 
-* Minimize verbs ending with "ing": "This is necessary to provide...",
-  not "This is necessary for providing..."
+* __Use Action Verbs__: Avoid weak verbs like "is" or "has." The
+  sentence in the item above could stand improvement.
 
-* Do not drop articles: "In the Bada IDE", not "In Bada IDE"
+* __Noun Phrase Jargon__: Avoid noun modification concatenation
+  somnambulation obfuscation.  Use your judgement and ask yourself if
+  readers might not actually know what some noun phrase means. If so,
+  explain the actual concept it represents, in this case: "Avoid
+  stringing nouns together into long phrases that come off as
+  impenetrable shop talk that puts everybody to sleep."
 
-* Possessives are OK: "the device's home screen" rather than clumsier:
-  "the home screen of the device"
+* __Use Possessives:__ Possessives sound more familiar and colloquial:
+  "the device's home screen" rather than clumsier: "the home screen of
+  the device"
 
-* 'The FOO file', not 'the file FOO', no matter how long FOO's
-  filename is.
+* __The Brothers Karmazov:__ 'The FOO file', not 'the file FOO', no
+  matter how long FOO's path is.
 
-* Hyphenate adjective phrases: "command-line tools", but not when it's
-  a noun, as in "the command line."
+* __Serial comma:__ This, that, and the other.
 
-* Use serial comma: this, that, and the other.
+* Do not drop articles: "In the Bada IDE", not "In Bada IDE"
 
-* Do not start a sentence with a lowercase member name.
+* Do not start a sentence with a lowercase member name. E.g., "Does
+  not support `filter`" rather than "`filter` is not supported"
 
 * Do not refer to "I," the author of the documentation, as in "What I
   am going to show you now." Likewise avoid "we" and "let's," so
@@ -191,6 +170,31 @@ immensely.
 
 * This Guide or section, not this document, page, or anything else
 
+## In-line Font Formatting
+
+* Use `monospace` for all-purpose nouns used in programming, e.g.: API
+  interfaces, methods, properties, literal values, Unix commands,
+  pathnames, filenames, etc.
+
+* Use __bold__ for on-screen items, such as the names of menu items,
+  buttons, and check boxes.
+
+* Use _italics_ for emphasis, simple mathematical expressions, and
+  variable items (e.g., _x_/_y_ coordinates).
+
+* Do _not_ use ALL CAPS for emphasis. (Exception: in commented code)
+
+* Do _not_ use "quote characters" to deliniate in-line text unless
+  required as part of a value. E.g., not OK to refer to the
+  "text-align" property. OK to set the CSS `text-align` property to
+  `left`, and the `content` property to `"This is some text."`
+  (Exception: within code comments)
+
+* Do not combine in-line formatting such as _`monospace italic`_.
+
+* Use the markup system's shorthand characters rather than embedded
+  HTML `<em>...</em>` or `<code>...</code>`.
+
 ## Usage
 
 * "User" may refer to the end user, not to the application's
@@ -275,6 +279,15 @@ immensely.
 
 ## Common Grammatical Errors
 
+* __Hyphenate Adjective Phrases:__ E.g., "command-line tools", but not
+  when it's a noun, as in "the command line."
+
+* __It's a Crazy Language, but its Rules Eventually Make Sense__:
+  Hyphenate "it's" only for "it is," not for possessive.
+
+* __Plural Possessives__: E.g., Obtain a user's permission, but
+  collectively, get users' permission.
+
 * Do not use use apostrophes for plural, so "...manages core APIs,"
   not api's or API's. Only use apostrophes for possessives, e.g. "the
   API's members"