docs: refresh documentation store (#3177)

.github/ISSUE_TEMPLATE/bug_report.md

@@ -10,7 +10,7 @@ assignees: ''
 **Describe the bug**
 
 **Steps To Reproduce**
-<!-- Please include the apimodel used to deploy the cluster if applicable (make sure to redact any secrets) -->
+<!-- Please include the API model used to deploy the cluster if applicable (make sure to redact any secrets) -->
 
 **Expected behavior**
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,12 +1,12 @@
-<!-- Thank you for helping aks-engine with a pull request!
+<!-- Thank you for helping AKS Engine with a pull request!
 Use conventional commit messages, such as
   feat: add a knob to the frobnitz
 or
   fix: repair hole in wumpus
 And read this for faster PR reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews -->
 
 **Reason for Change**:
-<!-- What does this PR improve or fix in aks-engine? -->
+<!-- What does this PR improve or fix in AKS Engine? -->
 
 
 **Issue Fixed**:

.prowci/README.md

@@ -4,7 +4,7 @@ Prow is a CI system that offers various features such as rich Github automation,
 and running tests in Jenkins or on a Kubernetes cluster. You can read more about
 Prow in [upstream docs][0].
 
-## aks-engine setup
+## AKS Engine setup
 
 Deploy a new Kubernetes cluster.
 

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing Guidelines
 
-The Microsoft aks-engine project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted.
+The Microsoft AKS Engine project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted.
 
 Please see also the [AKS Engine Developer Guide](docs/community/developer-guide.md).
 
@@ -35,11 +35,11 @@ specific upcoming bug or minor release, it would go into `2.2.1` or `2.3.0`.
 A milestone (and hence release) is considered done when all outstanding issues/PRs have been closed or moved to another milestone.
 
 ## Issues
-Issues are used as the primary method for tracking anything to do with the aks-engine project.
+Issues are used as the primary method for tracking anything to do with the AKS Engine project.
 
 ### Issue Lifecycle
 The issue lifecycle is mainly driven by the core maintainers, but is good information for those
-contributing to aks-engine. All issue types follow the same general lifecycle. Differences are noted below.
+contributing to AKS Engine. All issue types follow the same general lifecycle. Differences are noted below.
 1. Issue creation
 2. Triage
     - The maintainer in charge of triaging will apply the proper labels for the issue. This

cmd/addpool.go

@@ -52,8 +52,8 @@ type addPoolCmd struct {
 
 const (
 	addPoolName             = "addpool"
-	addPoolShortDescription = "Add a node pool to an existing Kubernetes cluster"
-	addPoolLongDescription  = "Add a node pool to an existing Kubernetes cluster by referencing a new agentpoolProfile spec"
+	addPoolShortDescription = "Add a node pool to an existing AKS Engine-created Kubernetes cluster"
+	addPoolLongDescription  = "Add a node pool to an existing AKS Engine-created Kubernetes cluster by referencing a new agentpoolProfile spec"
 )
 
 // newAddPoolCmd run a command to add an agent pool to a Kubernetes cluster

cmd/deploy.go

@@ -170,7 +170,7 @@ func (dc *deployCmd) mergeAPIModel() error {
 			return errors.Wrapf(err, "error merging --set values with the api model: %s", dc.apimodelPath)
 		}
 
-		log.Infoln(fmt.Sprintf("new api model file has been generated during merge: %s", dc.apimodelPath))
+		log.Infoln(fmt.Sprintf("new API model file has been generated during merge: %s", dc.apimodelPath))
 	}
 
 	return nil

cmd/generate.go

@@ -132,7 +132,7 @@ func (gc *generateCmd) mergeAPIModel() error {
 			return errors.Wrap(err, "error merging --set values with the api model")
 		}
 
-		log.Infoln(fmt.Sprintf("new api model file has been generated during merge: %s", gc.apimodelPath))
+		log.Infoln(fmt.Sprintf("new API model file has been generated during merge: %s", gc.apimodelPath))
 	}
 
 	return nil

cmd/rotate_certs.go

@@ -32,7 +32,7 @@ import (
 
 const (
 	rotateCertsName             = "rotate-certs"
-	rotateCertsShortDescription = "Rotate certificates on an existing Kubernetes cluster"
+	rotateCertsShortDescription = "Rotate certificates on an existing AKS Engine-created Kubernetes cluster"
 	rotateCertsLongDescription  = "Rotate CA, etcd, kubelet, kubeconfig and apiserver certificates in a cluster built with AKS Engine. Rotating certificates can break component connectivity and leave the cluster in an unrecoverable state. Before performing any of these instructions on a live cluster, it is preferrable to backup your cluster state and migrate critical workloads to another cluster."
 	kubeSystemNamespace         = "kube-system"
 )

cmd/scale.go

@@ -59,8 +59,8 @@ type scaleCmd struct {
 
 const (
 	scaleName             = "scale"
-	scaleShortDescription = "Scale an existing Kubernetes cluster"
-	scaleLongDescription  = "Scale an existing Kubernetes cluster by specifying increasing or decreasing the node count of an agentpool"
+	scaleShortDescription = "Scale an existing AKS Engine-created Kubernetes cluster"
+	scaleLongDescription  = "Scale an existing AKS Engine-created Kubernetes cluster by specifying increasing or decreasing the number of nodes in a node pool"
 	apiModelFilename      = "apimodel.json"
 )
 

cmd/upgrade.go

@@ -31,8 +31,8 @@ import (
 
 const (
 	upgradeName             = "upgrade"
-	upgradeShortDescription = "Upgrade an existing Kubernetes cluster"
-	upgradeLongDescription  = "Upgrade an existing Kubernetes cluster, one minor version at a time"
+	upgradeShortDescription = "Upgrade an existing AKS Engine-created Kubernetes cluster"
+	upgradeLongDescription  = "Upgrade an existing AKS Engine-created Kubernetes cluster, one node at a time"
 )
 
 type upgradeCmd struct {

cmd/version.go

@@ -31,7 +31,7 @@ var (
 
 const (
 	versionName             = "version"
-	versionShortDescription = "Print the version of AKS Engine"
+	versionShortDescription = "Print the version of aks-engine"
 	versionLongDescription  = versionShortDescription
 )
 

docs/README.md

@@ -10,7 +10,7 @@ AKS Engine has a lot of documentation. A high-level overview of how it’s organ
 
 [Topic guides][] discuss key topics and concepts at a fairly high level and provide useful background information and explanation.
 
-[How-to guides][] are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than tutorials and assume some knowledge of how AKS Engine works.
+[How-to guides][] are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than tutorials and assume some knowledge of how the `aks-engine` tool works.
 
 [Community guides][] teach you about the AKS Engine community. It incudes information on the project's Code of Conduct, the planning process for the AKS Engine project itself, its release cycle, and how you can contribute to the project.
 

docs/community/README.md

@@ -9,9 +9,10 @@ Here you'll find documentation geared towards learning about the development pro
 
 AKS Engine is a community effort. As it keeps growing, we always need more people to help others. As soon as you learn AKS Engine, you can contribute in many ways:
 
-- Join the [#aks-engine-users][] Slack channel on <https://kubernetes.slack.com> and answer questions. By explaining AKS Engine to other users, you’re going to learn a lot about the tool yourself.
+- Join the [#aks-engine-users][] and/or [#aks-engine-dev][] public Slack channels on <https://kubernetes.slack.com> and answer questions. By explaining AKS Engine to other users, you’re going to learn a lot about the tool yourself.
 - Blog about AKS Engine. We syndicate all the AKS Engine blogs we know about on the [topics page](../topics/README.md); if you’d like to see your blog on that page, you are more than welcome to add it there.
 - Contribute to other projects that use AKS Engine, write documentation, or release your own code as an open-source extension. The ecosystem of extensions is a community effort; help us build it!
 
 
 [#aks-engine-users]: https://kubernetes.slack.com/archives/CU3N85WJK
+[#aks-engine-dev]: https://kubernetes.slack.com/archives/CU1CXUHN0

docs/community/developer-guide.md

@@ -38,7 +38,7 @@ Or on Windows (ensure Docker is configured for Linux containers on Windows):
 powershell ./makedev.ps1
 ```
 
-This make target mounts the `aks-engine` source directory as a volume into the Docker container, which means you can edit your source code in your favorite editor on your machine, while still being able to compile and test inside of the Docker container. This environment mirrors the environment used in the AKS Engine continuous integration (CI) system.
+This make target mounts the AKS Engine source directory as a volume into the Docker container, which means you can edit your source code in your favorite editor on your machine, while still being able to compile and test inside of the Docker container. This environment mirrors the environment used in the AKS Engine continuous integration (CI) system.
 
 When `make dev` completes, you will be left at a command prompt inside a Docker container.
 
@@ -62,17 +62,17 @@ Usage:
   aks-engine [command]
 
 Available Commands:
-  addpool       Add a node pool to an existing Kubernetes cluster
+  addpool       Add a node pool to an existing AKS Engine-created Kubernetes cluster
   completion    Generates bash completion scripts
   deploy        Deploy an Azure Resource Manager template
   generate      Generate an Azure Resource Manager template
   get-logs      Collect logs and current cluster nodes configuration.
   get-versions  Display info about supported Kubernetes versions
   help          Help about any command
-  rotate-certs  Rotate certificates on an existing Kubernetes cluster
-  scale         Scale an existing Kubernetes cluster
-  upgrade       Upgrade an existing Kubernetes cluster
-  version       Print the version of AKS Engine
+  rotate-certs  Rotate certificates on an existing AKS Engine-created Kubernetes cluster
+  scale         Scale an existing AKS Engine-created Kubernetes cluster
+  upgrade       Upgrade an existing AKS Engine-created Kubernetes cluster
+  version       Print the version of aks-engine
 
 Flags:
       --debug                enable verbose debug logs
@@ -86,9 +86,9 @@ Use "aks-engine [command] --help" for more information about a command.
 
 ### Building on Windows, OSX, and Linux
 
-If the above docker container conveniences don't work for your developer environment, below is per-platform guidance to help you set up your local dev environment manually to build AKS Engine from source.
+If the above docker container conveniences don't work for your developer environment, below is per-platform guidance to help you set up your local dev environment manually to build an `aks-engine` binary from source.
 
-Building AKS Engine from source has a few requirements for each of the platforms. Download and install the prerequisites for your platform: Windows, Linux, or Mac:
+Building an `aks-engine` binary from source has a few requirements for each of the platforms. Download and install the prerequisites for your platform: Windows, Linux, or Mac:
 
 #### Windows
 
@@ -138,7 +138,7 @@ Build aks-engine:
 
 ### Structure of the Code
 
-The code for the aks-engine project is organized as follows:
+The code for the AKS Engine project is organized as follows:
 
 - The individual programs are located in `cmd/`. Code inside of `cmd/`
   is not designed for library re-use.
@@ -212,12 +212,12 @@ Thorough guidance around effectively running E2E tests to validate source code c
 
 ### Debugging
 
-To debug `aks-engine` code directly, use the [Go extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go)
+To debug AKS Engine code directly, use the [Go extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go)
 for Visual Studio Code or use [Delve](https://github.com/go-delve/delve) at the command line.
 
 #### Visual Studio Code
 
-To debug `aks-engine` with [VS Code](https://code.visualstudio.com/), first ensure that you have the
+To debug AKS Engine with [VS Code](https://code.visualstudio.com/), first ensure that you have the
 [Go extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go) installed. Click
 the "Extensions" icon in the Activity Bar (on the far left), search for "go", then install the
 official Microsoft extension titled "Rich Go language support for Visual Studio Code."
@@ -228,8 +228,7 @@ Once installed, the Go extension will `go get` several helper applications, incl
 debugging support. You can read more about VS Code integration with Delve
 [here](https://github.com/Microsoft/vscode-go/wiki/Debugging-Go-code-using-VS-Code).
 
-Make sure you have the `aks-engine` code checked out to the appropriate location in your `$GOPATH`
-and open that directory in VS Code.
+Open the directory that you checked out the `aks-engine` repo to in VS Code.
 
 ##### Debugging Tests
 
@@ -243,7 +242,7 @@ To the right of "run test" appears a link saying "debug test": click it!
 
 ##### Debugging AKS Engine
 
-To debug `aks-engine` itself, the default Go debugging configuration in `.vscode/launch.json` needs
+To debug changes to AKS Engine source during active development, the default Go debugging configuration in `.vscode/launch.json` needs
 to be edited. Open that file (or just click the gear-shaped "Open launch.json" icon if you have the
 Debug panel open).
 
@@ -333,7 +332,7 @@ The following steps constitute the AKS Engine CI pipeline:
 
 ## Pull Requests and Generated Code
 
-To make it easier use AKS Engine as a library and to `go get github.com/Azure/aks-engine`, some
+To make it easier use AKS Engine source code as a library and to `go get github.com/Azure/aks-engine`, some
 generated Go code is committed to the repository. Your pull request may need to regenerate those
 files before it will pass the required `make ensure-generated` step.
 

docs/community/planning-process.md

@@ -1,10 +1,10 @@
 # Planning Process
 
-aks-engine features a lightweight process that emphasizes openness and ensures every community member can see project goals for the future.
+AKS Engine features a lightweight process that emphasizes openness and ensures every community member can see project goals for the future.
 
 ## The Role of Maintainers
 
-[Maintainers][] lead the aks-engine project. Their duties include proposing the Roadmap, reviewing and integrating contributions and maintaining the vision of the project.
+[Maintainers][] lead the AKS Engine project. Their duties include proposing the Roadmap, reviewing and integrating contributions and maintaining the vision of the project.
 
 ## Open Roadmap
 

docs/community/release-checklist.md

@@ -1,20 +1,20 @@
 # Releases
 
-aks-engine uses a [continuous delivery][] approach for creating releases. Every merged commit that passes
+AKS Engine uses a [continuous delivery][] approach for creating releases. Every merged commit that passes
 testing results in a deliverable that can be given a [semantic version][] tag and shipped.
 
 ## Master Is Always Releasable
 
 The master `git` branch of a project should always work. Only changes considered ready to be
 released publicly are merged.
 
-aks-engine depends on components that release new versions as often as needed. Fixing
+AKS Engine depends on components that release new versions as often as needed. Fixing
 a high priority bug requires the project maintainer to create a new patch release.
 Merging a backward-compatible feature implies a minor release.
 
 By releasing often, each release becomes a safe and routine event. This makes it faster
 and easier for users to obtain specific fixes. Continuous delivery also reduces the work
-necessary to release a product such as aks-engine, which depends on several external projects.
+necessary to release a product such as AKS Engine, which depends on several external projects.
 
 "Components" applies not just to AKS projects, but also to development and release
 tools, to orchestrator versions, to Docker base images, and to other Azure
@@ -35,7 +35,7 @@ See "[Creating a New Release](#creating-a-new-release)" for more detail.
 
 ## Semantic Versioning
 
-aks-engine releases comply with [semantic versioning][semantic version], with the "public API" broadly
+Releases of the `aks-engine` binary comply with [semantic versioning][semantic version], with the "public API" broadly
 defined as:
 
 - REST, gRPC, or other API that is network-accessible
@@ -45,12 +45,12 @@ defined as:
 - Integration with Azure public APIs such as ARM
 
 In general, changes to anything a user might reasonably link to, customize, or integrate with should
-be backward-compatible, or else require a major release. aks-engine users can be confident that upgrading
+be backward-compatible, or else require a major release. `aks-engine` users can be confident that upgrading
 to a patch or to a minor release will not break anything.
 
 ## Creating a New Release
 
-Let's go through the process of creating a new release of [aks-engine][].
+Let's go through the process of creating a new release of the [aks-engine][] binary.
 
 We will use **v0.32.3** as an example herein. You should replace this with the new version you're releasing.