Fix & improve building doc.

1 files changed, 82 insertions, 62 deletions

diff --git a/doc/BUILDING.md b/doc/BUILDING.md
index 9bdd842..b515c05 100644
--- a/doc/BUILDING.md
+++ b/doc/BUILDING.md
@@ -12,24 +12,24 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 
-
 # How to build IOSched
 
-Note: while these instructions allow you to build iosched, much of the
-functionality that depends on server APIs won't work because in order to
-do that you need to configure your own project in Google Developer
-Console, create API keys, etc. For more information about what you
-need to set up, refer to [Server side setup](#server-side-setup).
+This is a Gradle-based project that works best with [Android Studio].
 
-This is a Gradle-based project that works best with
-[Android Studio](http://developer.android.com/sdk/installing/studio.html)
+<hr>  
+> __Note I__: While the instructions below allow you to build IOSched, much of 
+    the functionality that depends on server APIs won't work because in order to
+    do that you need to configure your own project in Google Developer
+    Console (create API keys, etc). These additional steps required to set up, 
+    are outlined in the [Server side setup] section in this document.
 
-> __NOTE__: Building the project as-is requires the Android Wear SDK, which you
-    can download from http://developer.android.com/wear/. If you wish to build
-    without Android Wear support, please refer to the [Building without Android
-    Wear](#building-without-android-wear) section.
+> __NOTE II__: Building the project as-is requires the Android Wear SDK, which 
+    you can download from http://developer.android.com/wear/. If you NOT wish to
+    build with Android Wear support, further details can be found in the
+	[Building without Android Wear] section in this document.
+<hr> 
 
-To build the app:
+## Build the app
 
 1. Install the following software:
        - Android SDK:
@@ -40,10 +40,9 @@ To build the app:
          http://developer.android.com/sdk/installing/studio.html
 
 2. Run the Android SDK Manager by pressing the SDK Manager toolbar button
-   in Android Studio or by running the 'android' command in a terminal
+   in Android Studio or by running the `android` command in a terminal
    window.
 
-
 3. In the Android SDK Manager, ensure that the following are installed,
    and are updated to the latest available version:
        - Tools > Android SDK Platform-tools (rev 21 or above)
@@ -59,7 +58,7 @@ To build the app:
 
 4. Create a file in your working directory called local.properties,
    containing the path to your Android SDK. Use local.properties.example as a
-   model.
+   model. _(On Windows, use a double-backslash ("\\") as a path separator.)_
 
 5. Import the project in Android Studio:
 
@@ -67,89 +66,110 @@ To build the app:
     2. Navigate to and choose the settings.gradle file in this project
     3. Press OK
 
-6. Add your debug keystore to the project (save it as android/debug.keystore), 
+6. Add your debug keystore to the project (save it as android/debug.keystore),
     or modify the build.gradle file to point to your key.
 
-7. Choose Build > Make Project in Android Studio or run the following
+> __NOTE__: In debug mode, you sign your app with a debug certificate generated
+    by the Android SDK. This certificate has a private key and a known password.
+    To sign your app in release mode, you need to generate your own certificate.
+    If you haven't done so, please refer to the [App Signing] guide for further
+    details. If you wish to build with Android Wear support, please refer to the
+    [Packaging Wearable Apps] guide for further details.
+
+7.A Choose Build > Make Project in Android Studio or run the following
     command in the project root directory:
-   ```
+   ```sh
     ./gradlew clean assembleDebug
    ```
 8. To install on your test device:
 
-   ```
+   ```sh
     ./gradlew installDebug
    ```
 
-
 ## Building without Android Wear
 
-If you do not wish to build the Android Wear component, you can remove or
-comment out the following line on android/build.gradle:
-
+If you do NOT wish to build the Android Wear component, you need to make the two
+changes below.
+    1. Open android/build.gradle and remove (or comment out) the following line:
+   ```
       wearApp project(":Wearable")
-
-Also, remove ':Wearable' from settings.gradle, leaving only ':android'.
-
+   ```
+    2. Open settings.gradle and remove `':Wearable'`, leaving only `':android'`.
 
 # Server-side setup
 
-These steps are optional, in the sense that IOSched will build and run
-even if you don't set up the server side. However, unless you perform
-this setup, your build won't be able to use any of the Google APIs
-such as Google sign in, Google Drive integration, Google Maps integration,
-etc. So following the instructions in this section is highly
-recommended.
+These steps are optional, in the sense that IOSched will build and run even if
+you don't set up the server side. However, unless you perform this setup, your
+build won't be able to use any of the Google APIs such as Google sign in, Google
+Drive integration, Google Maps integration, etc. So following the instructions
+in this section is highly recommended.
 
-0. Change the project's package name to your own package name.
-To do that, you can set the "package" attribute of the <manifest>
-tag in AndroidManifest.xml.
+1. Change the project's package name to your own package name. To do that, you
+can set the "package" attribute of the <manifest> tag in AndroidManifest.xml.
 
-1. Create a project in the Google Developers Console,
-at https://cloud.google.com/console
+2. Create a project in the Google Developers Console, at
+     https://cloud.google.com/console
 
-2. Note your project's Project ID. It is a 11-12 digit sequence
-that appears in the URL, indicated by ########### below:
+3. Note your project's Project ID. It is a 11-12 digit sequence that appears in
+the URL; indicated by ########### below:
     ```
     https://console.developers.google.com/project/###########/...
     ```
     Write down this project ID number you will need it soon.
 
-3. In the APIs and Auth section, enable these APIs:
+4. Navigate to "APIs and auth" > "APIs" and enable all of the following APIs:
     - Drive API
     - Google Cloud Messaging for Android
     - Google Maps Android API v2
     - Google+ API
     - YouTube Data API v3
 
-4. In the Credentials section, create a Client ID for Android applications
-with your package name and your certificate fingerprint. As a reminder,
-you can get your debug certificate fingerprint by issuing this command:
-    ```
+5. Navigate to "APIs and auth" > "Credentials" and create a new Client ID for
+Android applications with the package name (as defined in AndroidManifest.xml in
+Step 1) and your debug certificate fingerprint. As a reminder, to get your debug
+certificate fingerprint, run the following command (on Windows, substitute
+`%USERPROFILE%` for `$HOME`):
+    ```sh
     keytool -exportcert -alias androiddebugkey \
         -keystore $HOME/.android/debug.keystore -list -v
     ```
-    It's also advisable to create a Client ID corresponding to your release
+    It's also advisable to create a 2nd Client ID corresponding to your release
     certificate as well. To get your release certificate's fingerprint, run:
-    ```
+    ```sh
     keytool -exportcert -alias your-key-name \
         -keystore /path/to/your/release/keystore/file -list -v
     ```
-
-5. Still in the Credentials section, create an API Key for Public API
-access. The key's type is Key for Android applications, and you should
-add both your debug and release certificate fingerprints in the
-list of accepted certificates. Note the API key you created. It's
-a long alphanumeric string with digits, letters and with a 
-few underscores.
-
-6. Enter your API Key from Step 5 into this file:
+> __NOTE__: In order to create a Client ID, you might be required to set up the
+    consent screen first! _(The screen that will be shown to users whenever you
+    request access to their private data using your Client ID.)_ To do so, go to
+    "APIs and auth" > "Consent screen", enter a "PRODUCT NAME" and click "Save".
+    Finally, go back to Step 5 to create your Client ID(s).
+
+6. Still at the "Credentials" page, create an API Key for Public API access.
+As a key type use _"Key for Android applications"_, and you should add both your
+debug and release certificate fingerprints in the list of accepted certificates.
+Note the API key you created. _(It's a long alphanumeric string that may contain
+digits, letters and underscores.)_
+
+7. Enter the API key from Step 6 into this file:
     ```
     android/src/main/res/values/maps_api_key.xml
     ```
-7. Enter your API key in the YOUTUBE_API_KEY constant in Config.java
-
-Done. IOSched should now work with Google sign in, Google Drive
-integration and Maps integration. Note that we did NOT include
-setting up GCM. For more information about this, see [CUSTOM.md](CUSTOM.md).
-
+8. Enter the API key from Step 6, as a value for the `YOUTUBE_API_KEY` constant,
+   into this file:
+    ```
+    android/src/main/java/com/google/samples/apps/iosched/Config.java
+    ```
+<hr>
+
+Done. IOSched should now work with Google sign in, Google Drive and Maps
+integration. Note that we did NOT include setting up GCM. For more information
+about this, see the [CUSTOM.md] file.
+
+[Android Studio]:http://developer.android.com/sdk/installing/studio.html
+[App Signing]:http://developer.android.com/tools/publishing/app-signing.html#studio
+[Building without Android Wear]:https://github.com/google/iosched/blob/master/doc/BUILDING.md#building-without-android-wear
+[CUSTOM.md]:https://github.com/google/iosched/blob/master/doc/CUSTOM.md
+[Packaging Wearable Apps]:http://developer.android.com/training/wearables/apps/packaging.html
+[Server side setup]:https://github.com/google/iosched/blob/master/doc/BUILDING.md#server-side-setup