From 5139949d5c53c53e283e5cefd90f51a308e29d0d Mon Sep 17 00:00:00 2001 From: liz abinante Date: Tue, 9 May 2017 11:37:49 -0700 Subject: [PATCH] docs: some stuff is easy, some stuff is not :zap: let's be more descriptive --- .../source/docs/basics/terminology.html.md | 4 ++-- website/source/docs/builders/azure.html.md | 2 +- website/source/docs/commands/index.html.md | 11 +++++----- .../docs/extending/custom-builders.html.md | 7 +++--- .../extending/custom-post-processors.html.md | 2 +- .../extending/custom-provisioners.html.md | 2 +- website/source/docs/extending/plugins.html.md | 9 ++++---- .../post-processors/docker-import.html.md | 4 ++-- .../docs/post-processors/docker-save.html.md | 2 +- .../docs/post-processors/docker-tag.html.md | 4 ++-- .../docs/post-processors/shell-local.html.md | 5 +++-- website/source/docs/templates/engine.html.md | 9 ++++---- .../docs/templates/post-processors.html.md | 5 ++--- .../docs/templates/user-variables.html.md | 22 +++++++++---------- .../source/guides/veewee-to-packer.html.md | 6 ++--- .../intro/getting-started/build-image.html.md | 2 +- .../intro/getting-started/install.html.md | 4 ++-- .../getting-started/parallel-builds.html.md | 3 ++- .../getting-started/remote-builds.html.md | 2 +- 19 files changed, 53 insertions(+), 52 deletions(-) diff --git a/website/source/docs/basics/terminology.html.md b/website/source/docs/basics/terminology.html.md index 3566b0587..10249e4ac 100644 --- a/website/source/docs/basics/terminology.html.md +++ b/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. diff --git a/website/source/docs/builders/azure.html.md b/website/source/docs/builders/azure.html.md index 5027ceb4c..0b63a7941 100644 --- a/website/source/docs/builders/azure.html.md +++ b/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 diff --git a/website/source/docs/commands/index.html.md b/website/source/docs/commands/index.html.md index f785fcc8d..b31f8e128 100644 --- a/website/source/docs/commands/index.html.md +++ b/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 diff --git a/website/source/docs/extending/custom-builders.html.md b/website/source/docs/extending/custom-builders.html.md index 6b5a7e708..dffabc838 100644 --- a/website/source/docs/extending/custom-builders.html.md +++ b/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 diff --git a/website/source/docs/extending/custom-post-processors.html.md b/website/source/docs/extending/custom-post-processors.html.md index 16035d590..901c08676 100644 --- a/website/source/docs/extending/custom-post-processors.html.md +++ b/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. diff --git a/website/source/docs/extending/custom-provisioners.html.md b/website/source/docs/extending/custom-provisioners.html.md index 582a5704d..2ac3c78e8 100644 --- a/website/source/docs/extending/custom-provisioners.html.md +++ b/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. diff --git a/website/source/docs/extending/plugins.html.md b/website/source/docs/extending/plugins.html.md index c6e19745d..29ec9e183 100644 --- a/website/source/docs/extending/plugins.html.md +++ b/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. diff --git a/website/source/docs/post-processors/docker-import.html.md b/website/source/docs/post-processors/docker-import.html.md index b88125337..6757473f6 100644 --- a/website/source/docs/post-processors/docker-import.html.md +++ b/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. diff --git a/website/source/docs/post-processors/docker-save.html.md b/website/source/docs/post-processors/docker-save.html.md index 98498bd3b..7b9507539 100644 --- a/website/source/docs/post-processors/docker-save.html.md +++ b/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. diff --git a/website/source/docs/post-processors/docker-tag.html.md b/website/source/docs/post-processors/docker-tag.html.md index 4925c62d7..c5ae93937 100644 --- a/website/source/docs/post-processors/docker-tag.html.md +++ b/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. diff --git a/website/source/docs/post-processors/shell-local.html.md b/website/source/docs/post-processors/shell-local.html.md index a2b58b8e2..1d4fbfe14 100644 --- a/website/source/docs/post-processors/shell-local.html.md +++ b/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 diff --git a/website/source/docs/templates/engine.html.md b/website/source/docs/templates/engine.html.md index d896b0d88..6c5eecc1e 100644 --- a/website/source/docs/templates/engine.html.md +++ b/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: diff --git a/website/source/docs/templates/post-processors.html.md b/website/source/docs/templates/post-processors.html.md index e54165810..4b354a085 100644 --- a/website/source/docs/templates/post-processors.html.md +++ b/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 diff --git a/website/source/docs/templates/user-variables.html.md b/website/source/docs/templates/user-variables.html.md index 3aa7af3ec..166da61fb 100644 --- a/website/source/docs/templates/user-variables.html.md +++ b/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 -understand what can be modified using variables in your template. +defined. This explicitness helps reduce the onboarding time for newcomers to your +template 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 {{user \`variable\`}}. 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 +{{user \`variable\`}}. 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 { diff --git a/website/source/guides/veewee-to-packer.html.md b/website/source/guides/veewee-to-packer.html.md index 0642ad7fe..710cbae72 100644 --- a/website/source/guides/veewee-to-packer.html.md +++ b/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 diff --git a/website/source/intro/getting-started/build-image.html.md b/website/source/intro/getting-started/build-image.html.md index 7f950b406..8cda5ae20 100644 --- a/website/source/intro/getting-started/build-image.html.md +++ b/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. diff --git a/website/source/intro/getting-started/install.html.md b/website/source/intro/getting-started/install.html.md index a0efa616a..884683e9f 100644 --- a/website/source/intro/getting-started/install.html.md +++ b/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 diff --git a/website/source/intro/getting-started/parallel-builds.html.md b/website/source/intro/getting-started/parallel-builds.html.md index 6619dbcc1..ec5918da3 100644 --- a/website/source/intro/getting-started/parallel-builds.html.md +++ b/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 diff --git a/website/source/intro/getting-started/remote-builds.html.md b/website/source/intro/getting-started/remote-builds.html.md index 7ee554110..c9566ec92 100644 --- a/website/source/intro/getting-started/remote-builds.html.md +++ b/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 {