doc(*): Documentation changes, suggestions, fixes (#548)

* doc(src/users/ssh-keys.md): include command add-ssh after key creation

* doc(src/troubleshooting/index.md): add notes for eventual ssh-agent env needs

* doc(src/quickstart/provider/gke/boot.md): add instructions on having kubectl script available

* doc(src/quickstart/provider/aws/boot.md): add instructions on having
kubectl script available

* doc(src/quickstart/provider/aws/install-aws.md): add note for required package

* doc(src/quickstart/install-cli-tools.md): add note for required package

* doc(src/installing-workflow/configuring-object-storage.md): add complimentary info for steps

* doc(src/quickstart/deploy-an-app.md): fix relative URL path

* doc(src/quickstart/provider/aws/boot.md): fix typos, output format and URLs

* doc(src/quickstart/provider/aws/dns.md): fix URL prefix

* doc(src/quickstart/deploy-an-app.md): reorg final section including deis keys:add

* doc(src/quickstart/install-cli-tools.md): add helmc binary to path

* doc(src/quickstart/install-cli-tools.md): include notes for Linux users

* doc(src/quickstart/install-cli-tools.md): add note about version numbers

* doc(various): fix typos

* doc(quickstart): use admonition note/important format.

* docs(cli-tools): update example version to 2.7.0

Author: ultimateboy

src/installing-workflow/configuring-object-storage.md

@@ -49,9 +49,9 @@ After setting a `STORAGE_TYPE` environment variable to the desired object storag
 !!! note
 	These environment variables should be set **before** running `helmc generate` in Step 5.
 
-**Option 2:** Using template file `tpl/generate_params.toml`
+**Option 2:** Using template file `tpl/generate_params.toml` available at `$(helmc home)/workspace/charts/workflow-v2.7.0`
 
-* Edit Helm Classic chart by running `helmc edit workflow-v2.7.0` and look for the template file `tpl/generate_params.toml`
+* Edit Helm Classic chart by running `helmc edit workflow-v2.7.0` and look for the template file `tpl/generate_params.toml` (make sure you have the `$EDITOR` environment variable set with your favorite text editor)
 * Update the `storage` parameter to reference the platform you are using, e.g. `s3`, `azure`, `gcs`, or `swift`
 * Find the corresponding section for your storage type and provide appropriate values including region, bucket names, and access credentials.
 * Save your changes to `tpl/generate_params.toml`.
@@ -61,7 +61,7 @@ After setting a `STORAGE_TYPE` environment variable to the desired object storag
 
 ### Step 5: Generate manifests
 
-Generate the Workflow chart by running `helmc generate -x manifests workflow-v2.7.0`.
+Generate the Workflow chart by running `helmc generate -x manifests workflow-v2.7.0` (if you have previously run this step, make sure you add `-f` to force its regeneration).
 
 ### Step 6: Verify credentials
 

src/quickstart/deploy-an-app.md

@@ -101,14 +101,20 @@ proper-barbecue-v18-cmd-rk644 up (v18)
 proper-barbecue-v18-cmd-0ag04 up (v18)
 ```
 
-Congratulations! You have deployed, configured, and scaled your first application using Deis Workflow. There is a lot
-more you can do with Deis Workflow, play around with the CLI:
+Congratulations! You have deployed, configured, and scaled your first application using Deis Workflow. 
+
+## Going Further
+There is a lot more you can do with Deis Workflow, play around with the CLI:
+
+!!! important
+    In order to have permission to push an app you must add a SSH key to your user on the Deis Workflow.
+    For more information, please check [Users and SSH Keys](../users/ssh-keys/) and [Troubleshooting Workflow](../troubleshooting/).
 
 * Roll back to a previous release with `deis rollback -a proper-barbecue`
 * See application logs with `deis logs -a proper-barbecue`
 * Try one of our other example applications like:
     * [deis/example-ruby-sinatra](https://github.com/deis/example-ruby-sinatra)
     * [deis/example-nodejs-express](https://github.com/deis/example-nodejs-express)
     * [deis/example-java-jetty](https://github.com/deis/example-java-jetty)
-* Read about using application [Buildpacks](../applications/using-buildpacks.md) or [Dockerfiles](../applications/using-dockerfiles.md)
+* Read about using application [Buildpacks](../applications/using-buildpacks) or [Dockerfiles](../applications/using-dockerfiles.md)
 * Join our [#community slack channel](https://slack.deis.io) and meet the team!

src/quickstart/install-cli-tools.md

@@ -10,12 +10,19 @@ Install the latest `deis` client for Linux or Mac OS X with:
 The installer places the `deis` binary in your current directory, but you
 should move it somewhere in your $PATH:
 
+    $ sudo ln -fs $PWD/deis /usr/local/bin/deis
+
+*or*:
+
     $ sudo mv $PWD/deis /usr/local/bin/deis
 
 Check your work by running `deis version`:
 
     $ deis version
-    2.1.0
+    2.7.0
+
+!!! note
+    Note that version numbers may vary as new releases become available
 
 ## Helm Classic Installation
 
@@ -25,9 +32,16 @@ Install the latest `helmc` cli for Linux or Mac OS X with:
 
     $ curl -sSL https://get.helm.sh | bash
 
-The installer places the `helm` binary in your current directory, but you
+!!! note
+    Note that the `unzip` package is a requirement for this command
+
+The installer places the `helmc` binary in your current directory, but you
 should move it somewhere in your $PATH:
 
+    $ sudo ln -fs $PWD/helmc /usr/local/bin/helmc
+
+*or*:
+
     $ sudo mv $PWD/helmc /usr/local/bin/helmc
 
 Check your work by running `helmc --version`:

src/quickstart/provider/aws/boot.md

@@ -5,14 +5,14 @@ guide uses AWS EC2 to boot a Kubernetes cluster using the open source provisioni
 
 ## Pre-requisites
 
-1. You need an active AWS account. Visit [](http://aws.amazon.com) to sign up
+1. You need an active AWS account. Visit [AWS portal](http://aws.amazon.com) to sign up
 2. You need AWS API keys with full access
-3. Install the AWS cli tools, you can find instructions for your platform at [](https://aws.amazon.com/cli/)
+3. Install the AWS cli tools, you can find instructions for your platform at [AWS Command Line Interface Site](https://aws.amazon.com/cli/)
 
 To verify that your CLI is configured properly, run `aws ec2 describe-regions`:
 
 ```
-$ aws ec2 describe-regions
+$ aws ec2 describe-regions --output=text
 REGIONS	ec2.eu-west-1.amazonaws.com	eu-west-1
 REGIONS	ec2.ap-southeast-1.amazonaws.com	ap-southeast-1
 REGIONS	ec2.ap-southeast-2.amazonaws.com	ap-southeast-2
@@ -74,6 +74,23 @@ Last, so you can easily identify instances in the AWS Console, specify an instan
 export INSTANCE_PREFIX=first-k8s
 ```
 
+## Setup kubectl CLI
+
+Very soon, we will need to use `kubectl` to check everything is running smoothly and
+for that let's get it on the $PATH.
+
+For Mac OS, run:
+
+    $ ln -fs $PWD/platforms/darwin/amd64/kubectl /usr/local/bin/kubectl
+
+For Linux, use this instead:
+
+    $ sudo ln -fs $PWD/platforms/linux/amd64/kubectl /usr/local/bin/kubectl
+
+!!! note
+    If you are using any other architecture, you can look at the `platforms/<os>/<arch>`
+    tree to see all the available binaries
+
 ## Boot Your First Cluster
 
 We are now ready to boot our first Kubernetes cluster on AWS!
@@ -252,7 +269,7 @@ admin@ip-172-20-0-9:~$
 ```
 
 When you are finished with the Kubernetes cluster, you may terminate the AWS resources by running
-`./clusters/kube-down.sh`. If you are using a new shell environement you will need to set the environment variables we
+`./cluster/kube-down.sh`. If you are using a new shell environment you will need to set the environment variables we
 used above so `kube-down.sh` can find the right cluster.
 
 You are now ready to [install Deis Workflow](install-aws.md)

src/quickstart/provider/aws/dns.md

@@ -28,7 +28,7 @@ names. The website for your registrar will provide detailed instructions and pri
 for registering your domain name. For more information, see the following resources:
 
  - To use Amazon Route 53 to register a domain name, see [Registering Domain Names Using Amazon Route 53](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html).
- - For a list of accredited registrars, see the [Accredited Registrar Directory](www.internic.net/regist.html).
+ - For a list of accredited registrars, see the [Accredited Registrar Directory](http://www.internic.net/regist.html).
 
 Next, use your DNS service, such as your domain registrar, to create a wildcard CNAME record to
 route queries to your load balancer. For more information, see the documentation for your DNS

src/quickstart/provider/aws/install-aws.md

@@ -37,6 +37,9 @@ Run the following command to add this repository to Helm Classic:
 $ helmc repo add deis https://github.com/deis/charts
 ```
 
+!!! note
+   You need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed in order to run the command above
+
 ## Install Deis Workflow
 
 Now that you have Helm Classic installed and have added the Deis Chart Repository, install Workflow by running:

src/quickstart/provider/gke/boot.md

@@ -79,7 +79,12 @@ Fetching cluster endpoint and auth data.
 kubeconfig entry generated for cluster-1.
 ```
 
-Your local `kubectl` utility should now be pointed at your new container cluster. You can verify your crednentials and local configuration by running:
+If you don't have `kubectl` CLI setup just yet, run this to get it available
+locally:
+
+    $ gcloud components install kubectl
+
+Your local `kubectl` utility should now be pointed at your new container cluster. You can verify your credentials and local configuration by running:
 
 ```
 $ kubectl cluster-info

src/troubleshooting/index.md

@@ -19,6 +19,10 @@ The most common problem for this issue is the user forgetting to run `deis keys:
 private key to their SSH agent. To do so, run `ssh-add ~/.ssh/id_rsa` and try running
 `git push deis master` again.
 
+If you happen get a `Could not open a connection to your authentication agent` 
+error after trying to run `ssh-add` command above, you may need to load the SSH
+agent environment variables issuing the `eval "$(ssh-agent)"` command before.
+
 ## Other Issues
 
 Running into something not detailed here? Please [open an issue][issue] or hop into

src/users/ssh-keys.md

@@ -29,6 +29,8 @@ The key's randomart image is:
 |         . o =   |
 |          .   .  |
 +-----------------+
+$ ssh-add ~/.ssh/id_deis
+Identity added: /Users/admin/.ssh/id_deis (/Users/admin/.ssh/id_deis)
 ```
 
 ## Adding and Removing SSH Keys