cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mwbro...@apache.org
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


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

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

----------------------------------------------------------------------
 STYLESHEET.md | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f64d900f/STYLESHEET.md
----------------------------------------------------------------------
diff --git a/STYLESHEET.md b/STYLESHEET.md
index 8aaa443..d14a0d2 100644
--- a/STYLESHEET.md
+++ b/STYLESHEET.md
@@ -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
+immensely.
 
 ## In-line Font Formatting
 


Mime
View raw message