You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mw...@apache.org on 2013/11/13 19:15:47 UTC
[2/2] docs commit: tightened up & sample recursive grep commands
tightened up & sample recursive grep commands
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/dfda6503
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/dfda6503
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/dfda6503
Branch: refs/heads/master
Commit: dfda65038bc0410b77083cfb6e1bd9a208f1ce14
Parents: ad3f66a
Author: Mike Sierra <ms...@adobe.com>
Authored: Mon Nov 11 17:05:32 2013 -0500
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Wed Nov 13 10:15:44 2013 -0800
----------------------------------------------------------------------
STYLESHEET.md | 186 ++++++++++++++++++++++++++++++++---------------------
1 file changed, 113 insertions(+), 73 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/dfda6503/STYLESHEET.md
----------------------------------------------------------------------
diff --git a/STYLESHEET.md b/STYLESHEET.md
index 123a89d..e795bcb 100644
--- a/STYLESHEET.md
+++ b/STYLESHEET.md
@@ -21,7 +21,9 @@ license: Licensed to the Apache Software Foundation (ASF) under one
Developers contributing to Cordova are already familiar with coding
best practices. What you'll find here are best practices when writing
-tech doc addressed to Cordova developers.
+tech doc addressed to Cordova developers. A consistent set of
+standards helps tie together doc, and makes it seem like it's written
+with one voice.
There are two basic kinds of tech doc: reference content and
expository "guide" content. Reference doc tends to be self-contained,
@@ -35,22 +37,32 @@ workflows. It may not be obvious, but if you first ask yourself what
purpose the doc you're editing serves, it improves its quality
immensely.
+These guidelines are not necessarily set in stone. If you think of
+alternatives or exceptions, please note them here. Some of the issues
+identified below are listed along with recursive `grep` commands to
+help identify them in Markdown.
+
## Structure and Flow
+* __Provide Context__: Each page of expository doc should start with a
+ short paragraph summarizing the subject matter, and serving as
+ necessary connective tissue to other doc. Link to other related &
+ prerequisite topics, especially for likely workflow scenarios.
+ E.g., Plugman doc is most appropriate for platform-specific
+ shell-tool workflow, not for the CLI even though it underlies it
+ invisibly.
+
* __Valid Heading Structure__: One title only (an A-head) at the top
of the page. No jumps to C-heads. Do not follow a heading with a
subheading with no intervening introductory text.
+ grep -hr '^#' * # Lists all headings; use '#' prefixes rather than underlines
+
* __Flatten Content__: Use B-heads to divide each page's content. Please
- avoid C-heads; readers tend to lose context once content gets that
- nested.
+ avoid C-heads. Readers tend to lose context once content gets that
+ nested. Think: "blog post."
-* __Provide Context__: Each page of expository doc should start with a
- short paragraph summarizing the subject matter, and serving as
- necessary connective tissue. Link to other related & prerequisite
- topics, especially for likely workflow scenarios. E.g., Plugman doc
- is most appropriate for platform-specific shell-tool workflow, not
- for the CLI even though it underlies it invisibly.
+ grep -hr '^###' * # Identifies C-heads
* __Consistent Headings__: Try to match verb tense in headings. That
is, if one is task-based and reads "Adding a Platform," the other
@@ -58,11 +70,12 @@ immensely.
* __Heading Content__: In reference doc, preserve case in titles and
headings. In guide doc: Initial Cap Words in Headings, Except for
- Short Prepositions or Conjunctions. Also Init-Cap Around Hyphens,
- when each segment is a word rather than a prefix, e.g.:. No
- punctuation at the end of a heading; avoid punctuation within
+ Short Prepositions or Conjunctions. Also Init-Cap Around Hyphens. No
+ punctuation at the end of a heading, and avoid punctuation within
headings. Do not prefix headings with numbers.
+ grep -hr '^#' * | sed 's/^#*//g' | grep '[^A-Za-z0-9 ]'
+
* __Heading Fonts__: In reference doc, do not apply font formatting to
standalone member names such as compass.getCurrentHeading. Minimize
font changes within headings. If necessary, only apply italic.
@@ -71,10 +84,9 @@ immensely.
content only, otherwise use bullet lists. Precede lists with text
that introduces them, preferably ending with a colon (:). Do not
allow single-item lists. Use bullet lists only to indicate a clear
- set of choices that you first introduce, not as a substitute for
- regular paragraphs. Avoid nested lists, for the same reason you
- avoid C-heads. Do not nest top-level lists for additional
- indentation.
+ set of choices that you first introduce, not as a substitute for a
+ series of regular paragraphs. Avoid nested lists, for the same
+ reason you avoid C-heads. Do not indent top-level lists.
* __Punctuating and Formatting Lists__: Append periods to bullet and
number list items that consist of full sentences. No periods when
@@ -85,9 +97,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, then
+ (3) do that. 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
@@ -95,47 +107,61 @@ immensely.
punctuation. This list item provides an example. Bolded Topic Text
Follows Same Init-Cap Rule as Headings.
-* __Notes__: Bold & all-cap __NOTE__:, with colon outside, always at
- the start of a paragraph, never mid-paragraph. <!--RE :__--> Do not
- incorporate this font change into a sentence as in "__Note__
- that..." but OK to start a sentence: "Note that..." when the
- information is less consequential. Do not apply bullet/number list
- formatting. <!--RE- __NOTE-->
+* __Notes__: Bold and all-cap __NOTE__:, with colon outside, always at
+ the start of a paragraph, never mid-paragraph. Do not incorporate
+ this font change into a sentence as in "__Note__ that..." but OK to
+ start a sentence: "Note that..." when the information is less
+ consequential. Do not apply bullet/number list formatting.
+ grep -hr ':__' *
+ grep -hr ' __NOTE' *
+ grep -hr 'Note:' *
* __Warnings/Tips__: As an alternative to __NOTE__:, use __WARNING__:
for serious matters, or __TIP__: to pass along useful tricks or
context.
+ grep -hri 'Tip:' *
+ grep -hri 'Warning:' *
+
* __Minimize Notes__: Avoid too many notes and warnings, as it implies
a haphazard development environment with too many variable factors
that divert the reader's attention. Try to clarify variations on a
- procedure within the text.
-
-<!--
-* __Platform-Specific Notes__ __ios__: ???
--->
+ procedure within the text. Try to focus attention on information
+ specific to Cordova, not on background knowledge.
## Language and Tone
-* __Not So Imperitive__: As a rule of thumb, avoid the word "must" and
+* __Not So Imperative__: As a rule of thumb, avoid the word "must" and
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."
+ grep -hri '\<must\>' *
+ grep -r '\<requires*\>' *
+
* __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."
+ grep -hri '\<will\>' *
+
* __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".
Passive voice is more appropriate for reference doc, you should
still avoid it when there's a better active-voice alternative.
+ grep -hr '\<is [a-z]*ed\>' *
+ grep -hr '\<be [a-z]*ed\>' *
+ grep -hr '\<was [a-z]*ed\>' *
+
* __Not Kidding, Use Present Tense__: Minimize verbs ending with
"ing": "This is necessary to provide...", not "This is necessary for
providing..." <!-- are\s-+[a-z]+ing\b -->
+ grep -hr '\<for [a-z]*ing\>' *
+ grep -hr '\<by [a-z]*ing\>' *
+
* __Use Action Verbs__: Avoid weak verbs like "is" or "has." The
sentence in the item above could stand improvement.
@@ -150,8 +176,11 @@ immensely.
"the device's home screen" rather than clumsier: "the home screen of
the device"
+ grep -hr '\<of the\>' *
+
* __The Brothers Karmazov__: 'The FOO file', not 'the file FOO', no
- matter how long FOO's path is.
+ matter how long FOO's path is. Rule of thumb: would you say it when
+ speaking out loud?
* __Serial comma__: This, that, and the other.
@@ -159,23 +188,29 @@ immensely.
* Do not start a sentence with a lowercase member name. E.g., "Does
not support `filter`" rather than "`filter` is not supported"
- <!--RE \. `-->
+
+ grep -hr '\. `' *
* 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
- instead of "We see that..." try "Note that..." Readers want to focus
- on the thing they're working on, not on you. <!--RE \bI\b-->
+ instead of "We see that..." try "You see that" or "Note that..."
+ Readers want to focus on whatever they're working on, not on you.
+
+ grep -hr '\<I\>' *
* OK to refer to "you," the developer, but only sparingly, e.g., to
- avoid passive voice. Also do not use "your" as a routine substitute
- for "the" or "a" when referring to a noun.
+ avoid the passive voice. Also do not use "your" as a routine
+ substitute for "the" or "a" when referring to a noun.
+
+ grep -hri '\<your*\>' *
* Avoid em dash clauses--they unnecessarily break up the text--and
parenthical statements (which can also be distracting). If you do
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
+* Refer to this Guide or section, not this document, page, or anything
+ else.
## In-line Font Formatting
@@ -189,12 +224,12 @@ immensely.
* 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 ALL CAPS for emphasis. (Exception: in code comments)
* 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."`
+ `left`, and the `content` property to `"This is some quoted text."`
(Exception: within code comments)
* Do not combine in-line formatting such as _`monospace italic`_.
@@ -205,27 +240,31 @@ immensely.
## Usage
* "User" may refer to the end user, not to an application's
- "developer." Refer to plural "users" as "they" to avoid singular
- he/she pronoun problems. Also avoid "his" and "her".
- <!--RE\bs?he\b--> <!--RE\b(his|her)\b-->
+ "developer" who is presumably reading the doc. Refer to plural
+ "users" as "they" to avoid singular he/she pronoun problems. Also
+ avoid "his" and "her". <!--RE\bs?he\b--> <!--RE\b(his|her)\b-->
+
+ grep -hri '\<s*he\>' *
+ grep -hri '\<his\>' *
+ grep -hri '\<her\>' *
* WebView, not Webview. (OK to use lowercase webview in code)
* "In-line" rather than "inline" in ordinary text, e.g., outside of
technical terms.
-* "Plugman" in generic references, "plugman" when referring to actual
- utility.
+* "Plugman" in generic references, `plugman` when referring to the
+ actual utility as invoked on the command line.
* metadata.
* Xcode.
-* "splash screen" unless specifically referring to API.
+* "splash screen" unless specifically referring to the name of the API.
-* 'Directory', not 'folder'; may be exceptions in some GUI contexts
+* 'Directory', not 'folder'; may be exceptions in some GUI contexts.
-* Prefer "can't" over "cannot"; sounds more relaxed. <!--RE cannot-->
+* Prefer "can't" over "cannot"; sounds more relaxed.
* Subdirectory, not sub-directory
@@ -233,7 +272,7 @@ immensely.
* 'Set up' as verb, 'setup' as noun.
-* 'Handheld' not 'hand held'
+* 'handheld' not 'hand held' or 'hand-held'
* Filename, not file name
@@ -250,10 +289,11 @@ immensely.
* Prefer "emulator" over "simulator"; clarify when interfaces refer to
them differently.
-* Use "app" for mobile apps, and "application" for desktop. E.g., you
- may use the Xcode application to help you write an iOS Cordova app.
- Consider "app" a valid word rather than a contraction, so use "apps"
- rather than "app's" as plural.
+* Use "app" for mobile apps, and "application" for presumably more
+ complex desktop affairs. E.g., you may use the Xcode application to
+ help you write an iOS Cordova app. Consider "app" a valid word
+ rather than a contraction, so use "apps" rather than "app's" as
+ plural.
* Likewise, "repo" is OK to substitute for "repository"
@@ -263,20 +303,23 @@ immensely.
* Remove superfluous "navigate to" wherever possible, unless you need
to `cd` to a particular directory to launch a command. Instead of
- "Navigate to the D directory and edit the F file," prefer: "Edit the
- _D/F_ file."
+ "Navigate to the `D` directory and edit the `F` file," prefer: "Edit
+ the `D/F` file." And don't tell people which text editor to use.
+ That's fascist.
* An XML/HTML 'element' rather than 'tag'
-* It's a "method" when called on an object. Refer to "function" only
- when unspecified, e.g. a "callback function" may also be implemented
- as an object method.
+* Without getting into any pointless arguments about object-oriented
+ programming, it's a "method" when called on an object. Refer to
+ "function" only when unspecified, e.g. you can implement a "callback
+ function" as an object method, but not necessarily.
* Use parentheses when referring to `method()` and `function()` names.
(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
+* Spell out "and" and "or"; do not substitute with "&" or "/" within
+ text.
* "and/or" is unnecessary; "or" usually makes that implicit.
@@ -284,11 +327,12 @@ immensely.
in this example (but OK to refer to try/catch blocks).
* Avoid trailing (s) to denote optional plural. It's usually implicit.
- E.g., "return information about captured image files", not "file(s)"
+ E.g., "return information about any captured image files", not
+ "file(s)"
* Avoid the word "multiple" wherever possible. It's one of those
- unnecessary words up there with "myriad" or "plethora." What's wrong
- with "several"?
+ unnecessary words up there with "myriad" or "plethora." What ever
+ happened to "several"?
## Punctuation
@@ -322,14 +366,14 @@ immensely.
clauses where one is a sentence fragment. E.g., "This is a clause,
along with this." vs. "This can serve as a sentence; this can too."
-* If a sentence with semicolons runs on tool long, it's time to break
+* If a sentence with semicolons runs on too long, it's time to break
it out into separate sentences. Rewrite this... "This can serve as
a sentence; this can too, along with related information." ...as...
"This can serve as a sentence. This can too, along with related
information."
-* This is can serve as a sentence and this can also serve as a
- sentence but you need to use commas to separate this big mess.
+* This can serve as a sentence and this can also serve as a sentence
+ but you need to use commas to separate this big mess.
## Content-specific
@@ -343,26 +387,22 @@ immensely.
webview, e.g., custom plugins, or an embedded webview component. (2)
An app with an InAppBrowser, that is a web-based app that itself
opens a web page. Don't apply to a garden-variety "cross-platform"
- app that is Cordova's bread & butter.
+ app that is Cordova's bread and butter.
## Links
* Use titles in link text, never 'click here'. Consider using the
- link's domain name as a substitute. <!--RE here]-->
+ link's domain name as a substitute.
* Domain names are OK as a link's display text, but not full
scheme-qualified URLs. No bare URLs in text outside of code.
- <!--RE \[http -->
-## Miscellaneous
+ grep -hr '\[http' *
-* In body text, no ( extra space inside parens ). OK to increase
- readability of code.
+## Miscellaneous
* OK to use shorthand notation for version ranges, e.g. "5.0+" rather
than "(OS 5.0 and higher)"
* Use space characters rather than tabs in code blocks.
-
-