cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [01/17] docs commit: [CB-3962] distinguish guide/reference content up front
Date Mon, 04 Nov 2013 19:53:09 GMT
Updated Branches:
  refs/heads/master f4cd761ac -> 77386813f

[CB-3962] distinguish guide/reference content up front


Branch: refs/heads/master
Commit: f64d900f069ea98ee7ed7d8b0cd366cf17fc38a2
Parents: f4cd761
Author: Mike Sierra <>
Authored: Fri Nov 1 11:07:57 2013 -0400
Committer: Michael Brooks <>
Committed: Mon Nov 4 11:41:13 2013 -0800

---------------------------------------------------------------------- | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)
diff --git a/ b/
index 8aaa443..d14a0d2 100644
--- a/
+++ b/
@@ -17,10 +17,23 @@ license: Licensed to the Apache Software Foundation (ASF) under one
          under the License.
-# Style Sheet
-Before adding or editing documentation, please review these basic
-editorial guidelines.
+# Editorial Style Sheet
+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's end users.
+There are two basic kinds of tech doc: reference content and
+expository "guide" content. Reference doc tends to be self-contained,
+descriptive, and scoped without context: e.g., detailing an API
+interface and its members.  Guide content is prescriptive, linear, and
+part of a larger story. How do you typically use the API (or
+whatever), what do you need to know first, what are the limits to what
+you can use it for, etc. Guide content is oriented more around tasks,
+common use cases, or especially now in Cordova's case, alternative
+workflows.  It may not be obvious, but if you first ask yourself what
+purpose the doc you're editing serves, it improves its quality
 ## In-line Font Formatting

View raw message