Merge pull request #4866 from feministy/liz/docs-wording

docs: clarify language for "easy"/"simple", update website readme

website/README.md

@@ -12,7 +12,8 @@ like any normal GitHub project, and we'll merge it in.
 
 ## Running the Site Locally
 
-Running the site locally is simple. Clone this repo and run `make website`.
+1. Install [Docker](https://docs.docker.com/engine/installation/) if you have not already done so
+2. Clone this repo and run `make website`
 
 Then open up `http://localhost:4567`. Note that some URLs you may need to append
 ".html" to make them work (in the navigation).

website/source/docs/basics/terminology.html.md

@@ -6,7 +6,7 @@ description: |-
   the meaning may not be immediately obvious if you haven't used Packer before.
   Luckily, there are relatively few. This page documents all the terminology
   required to understand and use Packer. The terminology is in alphabetical
-  order for easy referencing.
+  order for quick referencing.
 ---
 
 # Packer Terminology
@@ -15,7 +15,7 @@ There are a handful of terms used throughout the Packer documentation where the
 meaning may not be immediately obvious if you haven't used Packer before.
 Luckily, there are relatively few. This page documents all the terminology
 required to understand and use Packer. The terminology is in alphabetical order
-for easy referencing.
+for quick referencing.
 
 - `Artifacts` are the results of a single build, and are usually a set of IDs or
   files to represent a machine image. Every builder produces a single artifact.

website/source/docs/builders/azure.html.md

@@ -217,7 +217,7 @@ builder.
 
 The Azure builder uses ARM
 [templates](https://azure.microsoft.com/en-us/documentation/articles/resource-group-authoring-templates/) to deploy
-resources.  ARM templates make it easy to express the what without having to express the how.
+resources.  ARM templates allow you to express the what without having to express the how.
 
 The Azure builder works under the assumption that it creates everything it needs to execute a build.  When the build has
 completed it simply deletes the resource group to cleanup any runtime resources.  Resource groups are named using the

website/source/docs/commands/index.html.md

@@ -35,8 +35,9 @@ However, Packer was built with automation in mind. To that end, Packer supports
 a fully machine-readable output setting, allowing you to use Packer in automated
 environments.
 
-The machine-readable output format is easy to use and read and was made with
-Unix tools in mind, so it is awk/sed/grep/etc. friendly.
+Because the machine-readable output format was made with Unix tools in mind, it
+is `awk`/`sed`/`grep`/etc. friendly and provides a familiar interface without
+requiring you to learn a new format.
 
 ### Enabling Machine-Readable Output
 
@@ -64,8 +65,8 @@ environments.
 ### Format for Machine-Readable Output
 
 The machine readable format is a line-oriented, comma-delimited text format.
-This makes it extremely easy to parse using standard Unix tools such as awk or
-grep in addition to full programming languages like Ruby or Python.
+This makes it more convenient to parse using standard Unix tools such as `awk` or
+`grep` in addition to full programming languages like Ruby or Python.
 
 The format is:
 
@@ -92,7 +93,7 @@ Each component is explained below:
 
 Within the format, if data contains a comma, it is replaced with
 `%!(PACKER_COMMA)`. This was preferred over an escape character such as `\'`
-because it is more friendly to tools like awk.
+because it is more friendly to tools like `awk`.
 
 Newlines within the format are replaced with their respective standard escape
 sequence. Newlines become a literal `\n` within the output. Carriage returns

website/source/docs/extending/custom-builders.html.md

@@ -25,8 +25,8 @@ recommend getting a bit more comfortable before you dive into writing plugins.
 ## The Interface
 
 The interface that must be implemented for a builder is the `packer.Builder`
-interface. It is reproduced below for easy reference. The actual interface in
-the source code contains some basic documentation as well explaining what each
+interface. It is reproduced below for reference. The actual interface in the
+source code contains some basic documentation as well explaining what each
 method should do.
 
 ```go
@@ -109,8 +109,7 @@ respond to these cancellations and clean up after itself.
 
 The `Run` method is expected to return an implementation of the
 `packer.Artifact` interface. Each builder must create their own implementation.
-The interface is very simple and the documentation on the interface is quite
-clear.
+The interface has ample documentation to help you get started.
 
 The only part of an artifact that may be confusing is the `BuilderId` method.
 This method must return an absolutely unique ID for the builder. In general, I

website/source/docs/extending/custom-post-processors.html.md

@@ -30,7 +30,7 @@ recommend getting a bit more comfortable before you dive into writing plugins.
 ## The Interface
 
 The interface that must be implemented for a post-processor is the
-`packer.PostProcessor` interface. It is reproduced below for easy reference. The
+`packer.PostProcessor` interface. It is reproduced below for reference. The
 actual interface in the source code contains some basic documentation as well
 explaining what each method should do.
 

website/source/docs/extending/custom-provisioners.html.md

@@ -29,7 +29,7 @@ recommend getting a bit more comfortable before you dive into writing plugins.
 ## The Interface
 
 The interface that must be implemented for a provisioner is the
-`packer.Provisioner` interface. It is reproduced below for easy reference. The
+`packer.Provisioner` interface. It is reproduced below for reference. The
 actual interface in the source code contains some basic documentation as well
 explaining what each method should do.
 

website/source/docs/extending/plugins.html.md

@@ -78,7 +78,7 @@ standpoint.
 Packer plugins must be written in [Go](https://golang.org/), so it is also
 assumed that you're familiar with the language. This page will not be a Go
 language tutorial. Thankfully, if you are familiar with Go, the Go toolchain
-makes it extremely easy to develop Packer plugins.
+provides many conveniences to help to develop Packer plugins.
 
 ~> **Warning!** This is an advanced topic. If you're new to Packer, we
 recommend getting a bit more comfortable before you dive into writing plugins.
@@ -104,9 +104,10 @@ process. Pretty cool.
 
 ### Plugin Development Basics
 
-Developing a plugin is quite simple. All the various kinds of plugins have a
-corresponding interface. The plugin simply needs to implement this interface and
-expose it using the Packer plugin package (covered here shortly), and that's it!
+Developing a plugin allows you to create additional functionality for Packer.
+All the various kinds of plugins have a corresponding interface. The plugin needs
+to implement this interface and expose it using the Packer plugin package
+(covered here shortly), and that's it!
 
 There are two packages that really matter that every plugin must use. Other than
 the following two packages, you're encouraged to use whatever packages you want.

website/source/docs/post-processors/docker-import.html.md

@@ -22,8 +22,8 @@ registry.
 
 ## Configuration
 
-The configuration for this post-processor is extremely simple. At least a
-repository is required.
+The configuration for this post-processor only requires a `repository`, a `tag`
+is optional.
 
 - `repository` (string) - The repository of the imported image.
 

website/source/docs/post-processors/docker-save.html.md

@@ -24,7 +24,7 @@ familiar with this and vice versa.
 
 ## Configuration
 
-The configuration for this post-processor is extremely simple.
+The configuration for this post-processor only requires one option.
 
 - `path` (string) - The path to save the image.
 

website/source/docs/post-processors/docker-tag.html.md

@@ -25,8 +25,8 @@ that this works with committed resources, rather than exported.
 
 ## Configuration
 
-The configuration for this post-processor is extremely simple. At least a
-repository is required.
+The configuration for this post-processor requires `repository`, all other settings
+are optional.
 
 - `repository` (string) - The repository of the image.
 

website/source/docs/post-processors/shell-local.html.md

@@ -11,8 +11,9 @@ description: |-
 
 Type: `shell-local`
 
-The local shell post processor executes scripts locally during the post processing stage. Shell local provides an easy
-way to automate executing some task with the packer outputs.
+The local shell post processor executes scripts locally during the post
+processing stage. Shell local provides a convenient way to automate executing
+some task with the packer outputs.
 
 ## Basic example
 

website/source/docs/templates/engine.html.md

@@ -31,10 +31,11 @@ globally available functions.
 
 ## Syntax
 
-The syntax of templates is extremely simple. Anything template related happens
-within double-braces: `{{ }}`. Variables are prefixed with a period and
-capitalized, such as `{{.Variable}}` and functions are just directly within the
-braces, such as `{{timestamp}}`.
+The syntax of templates uses the following conventions:
+
+* Anything template related happens within double-braces: `{{ }}`
+* Variables are prefixed with a period and capitalized, such as `{{.Variable}}`
+* Functions are directly within the braces, such as `{{timestamp}}`
 
 Here is an example from the VMware VMX template that shows configuration
 templates in action:

website/source/docs/templates/post-processors.html.md

@@ -44,9 +44,8 @@ apply to, if you wish.
 
 Within the `post-processors` array in a template, there are three ways to define
 a post-processor. There are *simple* definitions, *detailed* definitions, and
-*sequence* definitions. Don't worry, they're all very easy to understand, and
-the "simple" and "detailed" definitions are simply shortcuts for the "sequence"
-definition.
+*sequence* definitions. Another way to think about this is that the "simple" and
+"detailed" definitions are shortcuts for the "sequence" definition.
 
 A **simple definition** is just a string; the name of the post-processor. An
 example is shown below. Simple definitions are used when no additional

website/source/docs/templates/user-variables.html.md

@@ -26,12 +26,11 @@ how configuration templates work yet, please read that page first.
 
 User variables must first be defined in a `variables` section within your
 template. Even if you want a variable to default to an empty string, it must be
-defined. This explicitness makes it easy for newcomers to your template to
+defined. This explicitness helps reduce the time it takes for newcomers to 
 understand what can be modified using variables in your template.
 
-The `variables` section is a simple key/value mapping of the variable name to a
-default value. A default value can be the empty string. An example is shown
-below:
+The `variables` section is a key/value mapping of the variable name to a default
+value. A default value can be the empty string. An example is shown below:
 
 ```json
 {
@@ -58,11 +57,10 @@ If the default value is `null`, then the user variable will be *required*. This
 means that the user must specify a value for this variable or template
 validation will fail.
 
-Using the variables is extremely easy. Variables are used by calling the user
-function in the form of <code>{{user \`variable\`}}</code>. This function can be
-used in *any value* within the template; in builders, provisioners, *anywhere
-outside the `variables` section*.   The user variable is available globally
-within the rest of the template.
+Variables are used by calling the user function in the form of
+<code>{{user \`variable\`}}</code>. This function can be used in *any value*
+within the template; in builders, provisioners, *anywhere outside the `variables`
+section*. The user variable is available globally within the rest of the template.
 
 ## Environment Variables
 
@@ -121,8 +119,8 @@ earlier set variables if it has already been set.
 ### From a File
 
 Variables can also be set from an external JSON file. The `-var-file` flag reads
-a file containing a basic key/value mapping of variables to values and sets
-those variables. The JSON file is simple:
+a file containing a key/value mapping of variables to values and sets
+those variables. An example JSON file may look like this:
 
 ```json
 {

website/source/guides/veewee-to-packer.html.md

@@ -30,9 +30,9 @@ $ gem install veewee-to-packer
 # ...
 ```
 
-Once installed, usage is easy! Just point `veewee-to-packer` at the
-`definition.rb` file of any template. The converter will output any warnings or
-messages about the conversion. The example below converts a CentOS template:
+Once installed, just point `veewee-to-packer` at the `definition.rb` file of any
+template. The converter will output any warnings or messages about the conversion.
+The example below converts a CentOS template:
 
 ```text
 $ veewee-to-packer templates/CentOS-6.4/definition.rb

website/source/intro/getting-started/build-image.html.md

@@ -175,7 +175,7 @@ you will also need to set `associate_public_ip_address` to `true`, or set up a
 
 Packer only builds images. It does not attempt to manage them in any way. After
 they're built, it is up to you to launch or destroy them as you see fit. If you
-want to store and namespace images for easy reference, you can use [Atlas by
+want to store and namespace images for quick reference, you can use [Atlas by
 HashiCorp](https://atlas.hashicorp.com). We'll cover remotely building and
 storing images at the end of this getting started guide.
 

website/source/intro/getting-started/install.html.md

@@ -4,7 +4,7 @@ sidebar_current: intro-getting-started-install
 page_title: Install Packer - Getting Started
 description: |-
   Packer must first be installed on the machine you want to run it on. To make
-  installation easy, Packer is distributed as a binary package for all supported
+  installation easier, Packer is distributed as a binary package for all supported
   platforms and architectures. This page will not cover how to compile Packer
   from source, as that is covered in the README and is only recommended for
   advanced users.
@@ -13,7 +13,7 @@ description: |-
 # Install Packer
 
 Packer must first be installed on the machine you want to run it on. To make
-installation easy, Packer is distributed as a [binary package](/downloads.html)
+installation easier, Packer is distributed as a [binary package](/downloads.html)
 for all supported platforms and architectures. This page will not cover how to
 compile Packer from source, as that is covered in the
 [README](https://github.com/hashicorp/packer/blob/master/README.md) and is only

website/source/intro/getting-started/parallel-builds.html.md

@@ -166,7 +166,8 @@ us-east-1: ami-376d1d5e
 
 As you can see, Packer builds both the Amazon and DigitalOcean images in
 parallel. It outputs information about each in different colors (although you
-can't see that in the block above) so that it is easy to identify.
+can't see that in the block above), making it is easier to identify the actions
+executed when you execute the command.
 
 At the end of the build, Packer outputs both of the artifacts created (an AMI
 and a DigitalOcean snapshot). Both images created are bare bones Ubuntu

website/source/intro/getting-started/remote-builds.html.md

@@ -86,7 +86,7 @@ when you click on the active build, you can view the logs in real-time.
 Now we have Atlas building an AMI with Redis pre-configured. This is great, but
 it's even better to store and version the AMI output so it can be easily
 deployed by a tool like [Terraform](https://www.terraform.io). The `atlas`
-[post-processor](/docs/post-processors/atlas.html) makes this process simple:
+[post-processor](/docs/post-processors/atlas.html) makes this process easier:
 
 ```json
 {