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/10/31 21:55:10 UTC
[07/14] docs commit: [CB-3962] cleanup wp7 platform guide

[CB-3962] cleanup wp7 platform guide


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

Branch: refs/heads/master
Commit: 0af1a1062fa6f07d2a1607df698c080955319eed
Parents: b0ada44
Author: Mike Sierra <ms...@adobe.com>
Authored: Thu Oct 31 12:33:00 2013 -0400
Committer: Michael Brooks <mi...@michaelbrooks.ca>
Committed: Thu Oct 31 13:51:35 2013 -0700

----------------------------------------------------------------------
 STYLESHEET.md                             | 47 +++++++++++---
 docs/en/edge/guide/platforms/wp7/index.md | 89 ++++++++++++++++----------
 2 files changed, 95 insertions(+), 41 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0af1a106/STYLESHEET.md
----------------------------------------------------------------------
diff --git a/STYLESHEET.md b/STYLESHEET.md
index 3084830..23efcee 100644
--- a/STYLESHEET.md
+++ b/STYLESHEET.md
@@ -56,8 +56,13 @@ editorial guidelines.
 
 * Only one top-level heading allowed: the page's title.
 
+* No punctuation at the end of a heading; avoid punctuation within
+  headings
+
 * Do not follow a heading with a subheading or a list with no
-  intervening text.
+  intervening introductory text.  In particular, use bullet lists only
+  to indicate a clear set of choices that you introduce, not as a
+  substitute for regular body 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
@@ -66,6 +71,8 @@ editorial guidelines.
 * Use numbered lists for sequential procedures only, otherwise use
   bullet lists.
 
+* Single-item lists are silly. Do not use them.
+
 * Do not prefix headings with numbers.
 
 * Punctuation at the end of bullet/number list items that consist of
@@ -77,14 +84,23 @@ editorial guidelines.
 
 ## Language and Tone
 
-* Use present tense. "This happens," not "this will happen." (Future
-  tense sounds like a tenuous prediction.)
+* Use present tense. "This happens," not "this will happen." Future
+  tense off as a tenuous prediction. Rule of thumb: avoid the word
+  "will." Tech writers derisively refer to this problem as "the
+  willies."
 
-* Passive voice is to be avoided. E.g., "the pause event fires
-  when..."  rather than "the pause event is fired when..."
+* 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".
 
 * Prefer action verbs over weak verbs like "is" or "has."
 
+* Avoid noun modification concatenation somnambulation obfuscation.
+  Assume the reader doesn't know what it means, and explain the actual
+  concept. In this case: "Avoid stringing nouns together into long
+  phrases that come off as impenetrable shop talk that puts everybody
+  to sleep."
+
 * Minimize verbs ending with "ing": "This is necessary to provide...",
   not "This is necessary for providing..."
 
@@ -105,10 +121,11 @@ editorial guidelines.
 
 * 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..."
+  instead of "We see that..." try "Note that..." Readers want to focus
+  on the thing they're working on, not on you.
 
-* OK to refer to "you," the developer, but only if necessary, e.g., to
-  avoid passive voice.
+* OK to refer to "you," the developer, but only sparingly, e.g., to
+  avoid passive voice. Also do not use "your" as a substitute for "the."
 
 * Avoid unnecessarily imperative statements, especially using the word
   "must." E.g., instead of "Commands must be run from a cmd or
@@ -212,6 +229,20 @@ editorial guidelines.
 * Do not hyphenate adverbs, as it's implict they modify verbs.  So,
   "commonly seen problems," not "commonly-seen problems"
 
+* Use semicolons to separate short, closely related clauses that can
+  stand alone gramattically as full sentences. Use commas to separate
+  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
+  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.
+
 ## Content-specific
 
 * Refer to the default app as "Hello World", regardless of what it

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0af1a106/docs/en/edge/guide/platforms/wp7/index.md
----------------------------------------------------------------------
diff --git a/docs/en/edge/guide/platforms/wp7/index.md b/docs/en/edge/guide/platforms/wp7/index.md
index 1feef3d..7c3733c 100644
--- a/docs/en/edge/guide/platforms/wp7/index.md
+++ b/docs/en/edge/guide/platforms/wp7/index.md
@@ -38,71 +38,94 @@ current interface.
 
 ## System Requirements
 
-- Operating System:
-    - Windows 7 or Windows 8 (Pro) or Windows Vista with SP2
-        - The 64-bit version (x64) of Windows is required for the SDK.
-        - The Pro version is recommended for running a device emulator.
+Use Windows 7 or Windows 8 (Pro) or Windows Vista with SP2.  The
+64-bit version (x64) of Windows is required for the SDK.  The Pro
+version is recommended for running a device emulator.
 
-- Register and pay for a [Windows Phone Dev Center](http://dev.windowsphone.com/en-us/publish) account if you want to install your app on a real device or submit it to Market Place.
+Register and pay for a [Windows Phone Dev
+Center](http://dev.windowsphone.com/en-us/publish) account if you want
+to install an app on a real device or submit it to Market Place.
 
-__NOTE:__ Running the SDK in Virtual Machine might present some challenges. You can read this blog post that gives insight on the solutions to develop for [Windows Phone on a Mac](http://aka.ms/BuildaWP8apponaMac).
+__NOTE:__ Running the SDK in Virtual Machine may present challenges.
+Read [Windows Phone on a Mac](http://aka.ms/BuildaWP8apponaMac) for
+insights on developing solutions.
 
 ## Install SDK and Cordova
 
-- Download and install the [Windows Phone SDK](http://www.microsoft.com/download/en/details.aspx?displaylang=en&amp;id=27570/)
+Download and install the [Windows Phone
+SDK](http://www.microsoft.com/download/en/details.aspx?displaylang=en&amp;id=27570/).
 
-- Download and extract the latest copy of [Cordova](http://phonegap.com/download). You will be working in the `lib\windows-phone-8\wp7` subdirectory, `lib\windows-phone-8\wp8` contains the Windwos Phone 8 version of Cordova.
+Download and extract the latest copy of
+[Cordova](http://phonegap.com/download). You will be working in the
+`lib\windows-phone-8\wp7` subdirectory, `lib\windows-phone-8\wp8`
+contains the Windwos Phone 8 version of Cordova.
 
-- Copy the `CordovaWP7_x_x_x.zip` file to the `\My Documents\Visual Studio 2012\Templates\ProjectTemplates\` directory.
+Copy the `CordovaWP7_x_x_x.zip` file to the `\My Documents\Visual
+Studio 2012\Templates\ProjectTemplates\` directory.
 
 ## Building the Template
 
-__NOTE:__ this step may not be required.  If the lib\windows-phone directory already contains a file CordovaWP7_x_x_x.zip then you may skip this step.
+__NOTE:__ this step may not be required.  Skip this step if the
+`lib\windows-phone` directory already contains a
+`CordovaWP7_x_x_x.zip` file.
 
-In order to simplify the development process, Cordova comes with a script to build Visual Studio templates. This allows for rapid creation of Cordova applications inside Visual Studio. This template can be modified if needed and the below steps indicate how to proceed if you want to generate the template.
+To simplify development, Cordova bundles a script to build Visual
+Studio templates, which you can modify if necessary.  The steps below
+show how to generate it.
 
-### Run the batch file to create and install the templates.
+### Run the Batch File to Create and Install the Templates
 
-- The root of the repo contains a file createTemplates.bat.  Double clicking this file will generate 2 .zip files. (CordovaWP7_x_x_x.zip and CordovaWP8_x_x_x.zip where x.x.x is the current version number)  To easily use these files in Visual Studio, copy them to 
-"My Documents\Visual Studio 2012\Templates\ProjectTemplates\" You will then be able to create new Apache Cordova Windows Phone apps from the Visual Studio File->New Project menu.
+The root of the repo contains a `createTemplates.bat` file.
+Double-clicking this file generates two `.zip` files:
+`CordovaWP7_x_x_x.zip` and `CordovaWP8_x_x_x.zip`, where _x.x.x_ is
+the current version number. To use these files easily in Visual
+Studio, copy them to the `My Documents\Visual Studio
+2012\Templates\ProjectTemplates\` subdirectory. You are then able to
+create new __Apache Cordova Windows Phone_ apps from Visual Studio's
+__File &rarr; New Project__ menu.
 
-- If you run the batch file from the command line, you can also call with a parameter to install automatically
+If you run the batch file from the command line, you can also call
+with a parameter to install automatically:
 
-Run the script :
+        >createTemplates.bat -install
 
-    >createTemplates.bat -install
+## Set up a New Project
 
-## Set up New Project
+- Open Visual Studio Express for Windows Phone and choose __New
+  Project__.
 
-- Open Visual Studio Express for Windows Phone and choose __New Project__.
-
-- Select __CordovaWP7__. (The version number is displayed in the template description.)
+- Select __CordovaWP7__. The version number displays in the template
+  description.
 
 - Give the project a name, and select __OK__.
 
-## Review the project structure
-
-- The `www` directory contains your Cordova `html/js/css` and any other resources included in your app.
+## Review the Project Structure
 
-- Any content that you add here needs to be a part of the Visual Studio project, and it must be set as content.
+The `www` directory features `html`, `js`, and `css` subdirectories
+and any other resources your app requires.
+Any additional content needs to be a part of the Visual Studio
+project, and it must be set as content.
 
-- Note: This screen capture was from the wp8 cordova-2.3.0 download, your listing will vary based on the actual version installed.
+The following sample structure represents a 2.3.0 project, but may
+vary depending on installed version:
 
 ![](img/guide/platforms/wp8/projectStructure.png)
 
 ## Build the Project for the Device
 
-In order to test your application on a device, the device must be registered. Click [here][register-url] to read documentation on deploying and testing on your Windows Phone 7.
+Before testing your application on a device, the device must be
+registered. Consult
+[Microsoft's documentation][http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff402565(v=vs.105).aspx]
+for details on how to deploy and test on Windows Phone 7. These are
+the basic steps:
 
 - Make sure your phone is connected, and the screen is unlocked.
 
-- In Visual Studio, select 'Device' from the top drop-down menu.
+- In Visual Studio, select __Device__ from the drop-down menu at the top.
 
-- Press the green __play__ button next to the main drop-down menu to start debugging, or type __F5__.
+- Press the green __play__ button next to the main drop-down menu to
+  start debugging, or else type __F5__.
 
 ![](img/guide/platforms/wp7/wpd.png)
 
-## Done!
-
-[register-url]: http://msdn.microsoft.com/en-us/library/windowsphone/develop/ff402565(v=vs.105).aspx
-
+At this point, you're done.