[CB-3962] specify various editorial conventions
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/a2b1719d Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/a2b1719d Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/a2b1719d Branch: refs/heads/master Commit: a2b1719d4adb3ae2dbf0f47ebdf7517aed6eb45d Parents: 4055dfe Author: Mike Sierra <[email protected]> Authored: Thu Jul 18 13:20:26 2013 -0400 Committer: Michael Brooks <[email protected]> Committed: Thu Jul 18 12:19:15 2013 -0700 ---------------------------------------------------------------------- STYLESHEET.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2b1719d/STYLESHEET.md ---------------------------------------------------------------------- diff --git a/STYLESHEET.md b/STYLESHEET.md index b4646bd..5ed1f2b 100644 --- a/STYLESHEET.md +++ b/STYLESHEET.md @@ -52,8 +52,9 @@ editorial guidelines. * Do not follow a heading with a subheading or a list with no intervening text. -* Avoid too many NOTEs, as it implies too many variables that can go - wrong. Try to clarify variations on a procedure within the text. +* Avoid too many NOTEs, as it implies too many variable factors that + can go wrong. Try to clarify variations on a procedure within the + text. ## Language and Tone @@ -97,6 +98,8 @@ editorial guidelines. include either, remove spaces around the dashes (punctuate fragments outside of paren's). (Punctuate full sentences inside of parens.) +* This Guide or section, not this document, page, or anything else + ## Usage * "User" may refer to the end user, not to the application's @@ -113,12 +116,18 @@ editorial guidelines. * 'Handheld' not 'hand held' +* Filename, not file name + * 'JavaScript' (but lowercase when MIME type) +* Unix, not unix + * Mac "OS X", not "OSX" * BlackBerry, not Blackberry +* "BlackBerry 10," not "BlackBerry10" + * Prefer "emulator" over "simulator"; clarify when interfaces refer to them differently. @@ -141,6 +150,13 @@ editorial guidelines. (Exception: when assigning a reference to the object rather than calling it as a method.) +* Spell out "and" and "or"; do not substitute with "&" or "/" in text + +* "and/or" is unnecessary; "or" usually makes that implicit. + +* Avoid unnecessary/gratuitous slash-delimited alternators in text, as + in this example (but OK to refer to try/catch blocks). + ## Punctuation * Initial Cap Words in Headings, Except for Short Prepositions or @@ -162,9 +178,18 @@ editorial guidelines. not api's or API's. Only use apostrophes for possessives, e.g. "the API's members" +* "applications" not "app's" for plural + * Do not hyphenate adverbs, as it's implict they modify verbs. So, "commonly seen problems," not "commonly-seen problems" +## Content-specific + +* Refer to the default app as "Hello World", regardless of what it + actually displays. + +* Refer to the default plugin demo as "Echo" + ## Miscellaneous * For procedure lists, don't break out separate items for (1) do this,
