spelled out abbreviations, moved HA example to HA docs, integrated some other suggestions from @chrislovecn

Author: Willem Mali

README.md

@@ -68,20 +68,6 @@ $ mv kops-linux-amd64 /usr/local/bin/kops   # Move the kops to /usr/local/bin
 ```
 
 
-### Developer From Source
-
-Go 1.8+ and make are required. You may need to do a full build including pushing protokube, nodeup, and kops to s3.
-
-See the [install notes](/docs/install.md) for more information.
-
-```console
-$ go get -d k8s.io/kops
-$ cd ${GOPATH}/src/k8s.io/kops/
-$ git checkout release
-$ make
-```
-
-At this time, Windows is not a supported platform.
 
 
 ## History
@@ -151,20 +137,10 @@ date +%V
 
 The maintainers and other community members are generally available on the [kubernetes slack](https://github.com/kubernetes/community#slack-chat) in [#kops](https://kubernetes.slack.com/messages/kops/), so come find and chat with us about how kops can be better for you!
 
-## Other Resources
-
- - Create [kubecfg settings for kubectl](/docs/tips.md#create-kubecfg-settings-for-kubectl)
- - Set up [add-ons](/docs/addons.md), to add important functionality to Kubernetes
- - Learn about [InstanceGroups](/docs/instance_groups.md); change
- instance types, number of nodes, and other options
- - Read about [networking options](/docs/networking.md)
- - Look at our [other interesting modes](/docs/commands.md#other-interesting-modes)
- - Full command line interface [documentation](/docs/cli/kops.md)
-
 
 ## GitHub Issues
 
-#### Bugs
+### Bugs
 
 If you think you have found a bug please follow the instructions below.
 
@@ -176,7 +152,7 @@ If you think you have found a bug please follow the instructions below.
 - Feel free to reach out to the kops community on [kubernetes slack](https://github.com/kubernetes/community#slack-chat)
 
 
-#### Features
+### Features
 
 We also use the issue tracker to track features. If you have an idea for a feature, or think you can help kops become even more awesome follow the steps below.
 

docs/README.md

@@ -1,9 +1,6 @@
 Documentation Index
 ===================
 
-This page serves as a categorized index for all `kops` documentation.
-
-
 Quick start
 -----------
 * [Getting started on AWS](aws.md)
@@ -13,8 +10,8 @@ Quick start
 Overview
 --------
 
-* [CLI](#cli)
-* [Introspection](#introspection)
+* [Command-line interface](#commandline-interface)
+* [Inspection](#inspection)
 * [`kops` design documents](#kops-design-documents)
 * [Networking](#networking)
 * [Operations](#operations)
@@ -23,7 +20,7 @@ Overview
 
 
 
-### CLI ###
+### Command-line interface ###
 
 * [CLI argument explanations](arguments.md)
 * [CLI reference](cli/kops.md)
@@ -35,7 +32,7 @@ Overview
     * how to point kubectl to your `kops` cluster
 
 
-### Introspection ###
+### Inspection ###
 
 * [Download `kops` configuration](download_config.md)
     * methods to download the current generated `kops` configuration
@@ -64,21 +61,20 @@ Overview
 * [Cluster addon manager](addon_manager.md)
 * [Cluster addons](addons.md)
 * [Cluster configuration management](changing_configuration.md)
-* [Cluster with HA creation example](advanced_create.md)
 * [Cluster upgrades and migrations](cluster_upgrades_and_migrations.md)
 * [`etcd` volume encryption setup](etcd_volume_encryption.md)
 * [`etcd` backup setup](etcd_backup.md)
 * [GPU setup](gpu.md)
 * [High Availability](high_availability.md)
 * [InstanceGroup images](images.md)
-    * how to modify IG images and information on available/tested images
+    * how to use other image for cluster nodes, and information on available/tested images
+* [`k8s` upgrading](upgrade.md)
+* [`kops` updating](update_kops.md)
+* [`kube-up` to `kops` upgrade](upgrade_from_kubeup.md)
 * [Label management](labels.md)
-    * for AWS instance tags and `k8s` node labels
-* [`kube-up` to `kops` migration](upgrade_from_kubeup.md)
+    * for cluster nodes
 * [Secret management](secrets.md)
-* [Single-master to multi-master migration](single-to-multi-master.md)
-* [`k8s` updating](upgrade.md)
-* [`kops` updating](update_kops.md)
+* [Single-master to multi-master update](single-to-multi-master.md)
 
 
 ### Security ###

docs/advanced_create.md

@@ -1,6 +1,8 @@
-# High Availability (HA)
+High Availability (HA)
+======================
 
-## Introduction
+Introduction
+-------------
 
 Kubernetes has two strategies for high availability:
 
@@ -27,7 +29,9 @@ In short:
 * A multi-node kops cluster can tolerate the outage of a single AZ
 * Federation will allow you to create "uber-clusters" that can tolerate a regional outage
 
-## Using Kops HA
+
+Using Kops HA
+-------------
 
 We can create HA clusters using kops, but only it's important to note that migrating from a single-master
 cluster to a multi-master cluster is a complicated operation (described [here](./single-to-multi-master.md)).
@@ -58,3 +62,27 @@ As a result there are a few considerations that need to be taken into account wh
   If we create 2 (or more) masters in the same AZ, then failure of the AZ will likely cause etcd to lose quorum
   and stop operating (with 3 nodes).  Running in the same AZ therefore increases the risk of cluster disruption,
   though it can be a valid scenario, particularly if combined with [federation](https://kubernetes.io/docs/user-guide/federation/).
+
+
+Advanced Example
+----------------
+
+Another example `create cluster` invocation for HA with [a private network topology](topology.md):
+
+```
+kops create cluster \
+    --node-count 3 \
+    --zones us-west-2a,us-west-2b,us-west-2c \
+    --master-zones us-west-2a,us-west-2b,us-west-2c \
+    --dns-zone example.com \
+    --node-size t2.medium \
+    --master-size t2.medium \
+    --node-security-groups sg-12345678 \
+    --master-security-groups sg-12345678,i-abcd1234 \
+    --topology private \
+    --networking weave \
+    --cloud-labels "Team=Dev,Owner=John Doe" \
+    --image 293135079892/k8s-1.4-debian-jessie-amd64-hvm-ebs-2016-11-16 \
+    ${NAME}
+```
+