Merge pull request #184 from Microsoft/doc_updates

Doc updates

Author: lostintangent

cli/README.md

@@ -227,11 +227,11 @@ When the metrics cell reports `No installs recorded`, that indicates that the se
 
 Once your app has been configured to query for updates against the CodePush server, you can begin releasing updates to it. In order to provide both simplicity and flexibility, the CodePush CLI includes three different commands for releasing updates:
 
-1. [General](#releasing-updates-general) - Simply uploads an update to the CodePush server, and therefore, provides the most flexibility in terms of how to generate the update in the first place (e.g. are you using a `gulp` task? running a custom shell script?), since it doesn't apply any opinion about it.
+1. [General](#releasing-updates-general) - Releases an update to the CodePush server that was generated by an external tool or build script (e.g. a Gulp task, the `react-native bundle` command). This provides the most flexibility in terms of fitting into existing workflows, since it strictly deals with CodePush-specific step, and leaves the app-specific compilation process to you.
 
-2. [React Native](#releasing-updates-react-native) - Performs the same functionality as the general release command, but also handles the work of generating the updated contents for you (JS bundle and assets), instead of requiring you to run both `react-native bundle` and then `code-push release`.
+2. [React Native](#releasing-updates-react-native) - Performs the same functionality as the general release command, but also handles the task of generating the updated app contents for you (JS bundle and assets), instead of requiring you to run both `react-native bundle` and then `code-push release`. 
 
-3. [Cordova](#releasing-updates-cordova) - Performs the same functionality as the general release command, but also handles the work of preparing the app update for you, instead of requiring you to run both `cordova prepare` and then `code-push release`.
+3. [Cordova](#releasing-updates-cordova) - Performs the same functionality as the general release command, but also handles the task of preparing the app update for you, instead of requiring you to run both `cordova prepare` and then `code-push release`. 
 
 Which of these commands you should use is mostly a matter of requirements and/or preference. However, we generally recommend using the relevant platform-specific command to start (since it greatly simplifies the experience), and then leverage the general-purpose `release` command if/when greater control is needed.
 
@@ -248,13 +248,13 @@ code-push release <appName> <updateContents> <targetBinaryVersion>
 
 #### App name parameter
 
-This specifies the name of the CodePush app that this update is being released for.
+This specifies the name of the CodePush app that this update is being released for. This value corresponds to the friendly name that you specified when originally calling `code-push app add` (e.g. "MyApp-Android"). If you need to look it up, you can run the `code-push app ls` command to see your list of apps.
 
 #### Update contents parameter
 
-This specifies the location of the code and assets you want to release. You can provide either a single file (e.g. a JS bundle for a React Native app), or a path to a directory (e.g. the `/platforms/ios/www` folder for a Cordova app). You don't need to zip up multiple files or directories in order to deploy those changes, since the CLI will automatically zip them for you.
+This specifies the location of the updated app code and assets you want to release. You can provide either a single file (e.g. a JS bundle for a React Native app), or a path to a directory (e.g. the `/platforms/ios/www` folder for a Cordova app). Note that you don't need to ZIP up multiple files or directories in order to deploy those changes, since the CLI will automatically ZIP them for you.
 
-It's important that the path you specify refers to the platform-specific, prepared/bundled version of your app. The following table outlines which command you should run before releasing, as well as the location you can subsequently point at using the `updateContents` parameter:
+It's important that the path you specify refers to the platform-specific, prepared/bundled version of your app. The following table outlines which command you should run before releasing, as well as the location you can subsequently refer to using the `updateContents` parameter:
 
 | Platform                         | Prepare command                                                                                                                                            | Package path (relative to project root)                                                                     |
 |----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
@@ -310,12 +310,6 @@ This provides an optional "change log" for the deployment. The value is simply r
 
 *NOTE: This parameter can be set using either "--description" or "-desc"*
 
-#### Disabled parameter
-
-This specifies whether an update should be disabled. A disabled update is one that is not acquirable by clients. If left unspecified, the update will not be disabled, i.e. clients configured to receive updates from the particular deployment will receive the update [if it applies to them](#target-binary-version-parameter).
-
-*NOTE: This parameter can be set using either "--disabled" or "-x"*
-
 #### Mandatory parameter
 
 This specifies whether the update should be considered mandatory or not (e.g. it includes a critical security fix). This attribute is simply round tripped to the client, who can then decide if and how they would like to enforce it.
@@ -354,6 +348,12 @@ This specifies the percentage of users (as an integer between `1` and `100`) tha
 
 *NOTE: This parameter can be set using either `--rollout` or `-r`* 
 
+#### Disabled parameter
+
+This specifies whether an update should be acquirable by end users or not. If left unspecified, the update will not be disabled (i.e. users will download it the moment your app calls `sync`). This parameter can be valuable if you want to release an update that isn't immediately available, until you expicitly [patch it](#patching-releases) when you want end users to be able to download it (e.g. an announcement blog post went live).
+
+*NOTE: This parameter can be set using either "--disabled" or "-x"*
+
 ### Releasing Updates (React Native)
 
 ```shell
@@ -407,10 +407,6 @@ This is the same parameter as the one described in the [above section](#app-name
 
 This specifies which platform the current update is targeting, and can be either `ios` or `android` (case-insensitive).
 
-#### Bundle name parameter
-
-This specifies the file name that should be used for the generated JS bundle. If left unspecified, the standard bundle name will be used for the specified platform: `main.jsbundle` (iOS) and `index.android.bundle` (Android).
-
 #### Deployment name parameter
 
 This is the same parameter as the one described in the [above section](#deployment-name-parameter).
@@ -419,34 +415,38 @@ This is the same parameter as the one described in the [above section](#deployme
 
 This is the same parameter as the one described in the [above section](#description-parameter).
 
-#### Development parameter
+#### Mandatory parameter
 
-This specifies whether to generate a unminified, development JS bundle. If left unspecified, this defaults to `false` where warnings are disabled and the bundle is minified.
+This is the same parameter as the one described in the [above section](#mandatory-parameter).
+
+#### Rollout parameter
+
+This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.
+
+#### Target binary version parameter
+
+This is the same parameter as the one described in the [above section](#target-binary-version-parameter). If left unspecified, this defaults to targeting the exact version specified in the app's `Info.plist` (for iOS) and `build.gradle` (for Android) files.
 
 #### Disabled parameter
 
 This is the same parameter as the one described in the [above section](#disabled-parameter).
 
+#### Development parameter
+
+This specifies whether to generate a unminified, development JS bundle. If left unspecified, this defaults to `false` where warnings are disabled and the bundle is minified.
+
 #### Entry file parameter
 
 This specifies the relative path to app's root/entry JavaScript file. If left unspecified, this defaults to `index.ios.js` (for iOS) or `index.android.js` (for Android) if that file exists, or `index.js` otherwise.
 
-#### Mandatory parameter
+#### Bundle name parameter
 
-This is the same parameter as the one described in the [above section](#mandatory-parameter).
+This specifies the file name that should be used for the generated JS bundle. If left unspecified, the standard bundle name will be used for the specified platform: `main.jsbundle` (iOS) and `index.android.bundle` (Android).
 
 #### Sourcemap output parameter
 
 This specifies the relative path to where the generated JS bundle's sourcemap file should be written. If left unspecified, sourcemaps will not be generated.
 
-#### Target binary version parameter
-
-This is the same parameter as the one described in the [above section](#target-binary-version-parameter). If left unspecified, this defaults to targeting the exact version specified in the app's `Info.plist` (for iOS) and `build.gradle` (for Android) files.
-
-#### Rollout parameter
-
-This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.
-
 ### Releasing Updates (Cordova)
 
 ```shell
@@ -495,25 +495,25 @@ This is the same parameter as the one described in the [above section](#deployme
 
 This is the same parameter as the one described in the [above section](#description-parameter).
 
-#### Disabled parameter
-
-This is the same parameter as the one described in the [above section](#disabled-parameter).
-
 #### Mandatory parameter
 
 This is the same parameter as the one described in the [above section](#mandatory-parameter).
 
+#### Rollout parameter
+
+This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.
+
 #### Target binary version parameter
 
 This is the same parameter as the one described in the [above section](#target-binary-version-parameter). If left unspecified, the command defaults to targeting only the specified version in the project's metadata (`Info.plist` if this update is for iOS clients, and `build.gradle` for Android clients).
 
-#### Rollout parameter
+#### Disabled parameter
 
-This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.
+This is the same parameter as the one described in the [above section](#disabled-parameter).
 
 ## Patching Updates
 
-After releasing an update, there may be scenarios where you need to modify one or more of the attributes associated with the release (e.g. you forgot to mark a critical bug fix as mandatory, you want to increase the rollout percentage of an update). You can easily do this by running the following command:
+After releasing an update, there may be scenarios where you need to modify one or more of the attributes associated with it (e.g. you forgot to mark a critical bug fix as mandatory, you want to increase the rollout percentage of an update). You can easily do this by running the following command:
 
 ```shell
 code-push patch <appName> <deploymentName>
@@ -525,9 +525,14 @@ code-push patch <appName> <deploymentName>
 
 Aside from the `appName` and `deploymentName`, all parameters are optional, and therefore, you can use this command to update just a single attribute or all of them at once. Calling the `patch` command without specifying any attribute flag will result in a no-op.
 
+```shell
+code-push patch MyApp Production -m
+code-push patch MyApp Production -l v23 -rollout 50%
+```
+
 #### Label Parameter
 
-Indicates which release (e.g. `v23`) you want to update within the specified deployment. If ommitted, the requested changes will be applied to the latest release in the specified deployment.
+Indicates which release (e.g. `v23`) you want to update within the specified deployment. If ommitted, the requested changes will be applied to the latest release in the specified deployment. In order to look up the label for the release you want to update, you can run the `code-push deployment history` command and refer to the `Label` column.
 
 *NOTE: This parameter can be set using either `--label` or `-l`*