(FM-8079) Docs edit

clairecadman · DavidS · commit 57901eaee9a3 · 2019-09-24T14:35:26.000+01:00
diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,7 @@
 # Resource API hands-on lab
 
-This lab will walk you through the basic steps of creating a native integration with puppet. After this you will have a fully functioning module to manage Philips HUE lights and have seen all the bits fall into place.
+The Resource API hands-on lab walks you through creating a native integration with Puppet. After completely this lab, you will have a fully functioning module to manage Philips HUE lights.
 
-These labs are intended for new and experienced developers alike. Please post feedback and suggestions for improvement in the [issues section](https://github.com/puppetlabs/puppet-resource_api/issues).
+>Note: These labs are intended for both new and experienced developers. If you have any feedback or suggestions for improvement, post it in the [issues section](https://github.com/puppetlabs/puppet-resource_api/issues).
 
-Start with [installing the Puppet Development Kit](./hands-on-lab/01-installing-prereqs.md)
+To start with, we'll go through [installing Puppet Development Kit](./hands-on-lab/01-installing-prereqs.md)(PDK).
diff --git a/docs/hands-on-lab/01-installing-prereqs.md b/docs/hands-on-lab/01-installing-prereqs.md
@@ -1,16 +1,16 @@
-# Install the Puppet Development Kit and other tools
+# Install Puppet Development Kit (PDK) and other tools
 
-To start out, install the Puppet Development Kit (PDK), which will provide all necessary tools and libraries to build and test modules. Additionally we recommend an emulator for the target device of this lab, a code editor with good ruby and puppet support, and GIT, a version control system to keep track of our progress.
+To start, install Puppet Development Kit (PDK), which provides all the necessary tools and libraries to build and test modules. We also recommend an emulator for the target device, a code editor with good Ruby and Puppet support, and git — a version control system to keep track of your progress.
 
-1. Choose your platform from https://puppet.com/download-puppet-development-kit; download and install the package
+1. [Download PDK](https://puppet.com/download-puppet-development-kit) on your platform of choice.
 
-2. If you do not have a Philips HUE hub available, you can download the [Hue-Emulator](https://github.com/SteveyO/Hue-Emulator/raw/master/HueEmulator-v0.8.jar). You will need to have Java installed to run this.
+2. If you do not have a Philips HUE hub available, you can download the [Hue-Emulator](https://github.com/SteveyO/Hue-Emulator/raw/master/HueEmulator-v0.8.jar). You need to have Java installed to run this.
 
 3. To edit code, we recommend the cross-platform editor [VSCode](https://code.visualstudio.com/download), with the [Ruby](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby) and [Puppet](https://marketplace.visualstudio.com/items?itemName=jpogran.puppet-vscode) extensions. There are lots of other extensions that can help you with your development workflow.
 
-4. Git is a version control system that helps you keep track of changes and collaborate with others. In the course of the hands-on lab, we will show some integrations with cloud services that can help you. If you never used git before, skip this and all related steps for now.
+4. Git is a version control system that helps you keep track of changes and collaborate with others. As we go through hands-on lab, we will show you some integrations with cloud services. If you have never used git before, ignore this and all related steps.
 
 
 ## Next up
 
-Having installed all of this, let's [light up a few](./02-connecting-to-the-lightbulbs.md).
+After installing the relevant tools, you'll [light up a few](./02-connecting-to-the-lightbulbs.md).
diff --git a/docs/hands-on-lab/02-connecting-to-the-lightbulbs.md b/docs/hands-on-lab/02-connecting-to-the-lightbulbs.md
@@ -1,28 +1,28 @@
-# Connecting to the Lightbulbs
+# Connecting to the light bulbs
 
-While there are no technical restrictions on the kinds of remote devices or APIs you can connect to with transports, for the purpose of this workshop we are connecting to a Philips HUE hub and make some colourful wireless lightbulbs light up. If you (understandably) do not have physical devices available, you can get going with the Hue Emulator.
+There are no technical restrictions on the kinds of remote devices or APIs you can connect to with transports. For this lab, we will connect to a Philips HUE hub and make some colourful wireless light bulbs light up. If you (understandably) do not have physical devices available, you can use the Hue Emulator.
 
 ## Hue Emulator
 
 Download the [HueEmulator-v0.8.jar](https://github.com/SteveyO/Hue-Emulator/blob/master/HueEmulator-v0.8.jar) from [SteveyO/Hue-Emulator](https://github.com/SteveyO/Hue-Emulator).
 
-To run this emulator, you will need to have a Java Runtime installed. Once you have java installed, use `java -jar` with the emulator's filename to run it:
+To run the Hue Emulator, you need to have a Java Runtime installed. Use `java -jar` with the emulator's filename to run it, for example:
 
 ```
 david@davids:~$ java -jar ~/Downloads/HueEmulator-v0.8.jar
 ```
 
-It will not produce any output on the command line, but it will pop up a window with a hub and a few predefined lights:
+It does not produce any output on the command line, but a window pops up with a hub and a few predefined lights:
 
 ![](./02-connecting-to-the-lightbulbs-emulator.png)
 
-All you need now is to input a port (the default 8000 is usually fine) and press "Start" to activate the built-in server.
+All you need now is to input a port (the default 8000 is usually fine) and click "Start" to activate the built-in server.
 
 ## Connecting to your hub
 
-To connect to an actual hub, you will need be able to access the Hub on your network and get an API key. Follow the [Philips Developer docs](http://www.developers.meethue.com/documentation/getting-started) (registration required) for that.
+To connect to an actual hub, you need be able to access the bub on your network and get an API key. See the [Philips Developer docs](http://www.developers.meethue.com/documentation/getting-started) (registration required).
 
 
 ## Next up
 
-Once you have some lights up, head on to [create a new module](./03-creating-a-new-module.md).
+Now that you have some lights up, you'll [create a module](./03-creating-a-new-module.md).
diff --git a/docs/hands-on-lab/03-creating-a-new-module.md b/docs/hands-on-lab/03-creating-a-new-module.md
@@ -1,26 +1,26 @@
-# Create a new module
+# Create a module
 
-Depending on your preferences, you can use the VSCode/PDK integration or run the PDK from the command line in a terminal of your choice.
+Depending on your preferences, you can use the VSCode/PDK integration or run PDK from the command line in a terminal of your choice.
 
-## VSCode
+## Create a module with VSCode
 
-Hit up the Command Palette (⇧⌘P on the Mac or Ctrl+Shift+P on Windows and Linux) and search for the `Puppet: PDK New Module` task:
+Spin up the Command Palette (⇧⌘P on the Mac or Ctrl+Shift+P on Windows and Linux) and search for the `Puppet: PDK New Module` task:
 
 ![](./03-creating-a-new-module_vscode.png)
 
-Press Enter (↩) to execute this and follow the on-screen prompts.
+Click Enter (↩) to execute this and follow the on-screen prompts.
 
 The module will open in a new VSCode window.
 
-## Command Line
+## Create a module from the command line
 
-In your regular workspace (for example your home directory) run
+In your regular workspace (for example your home directory), run the following:
 
 ```
 pdk new module hue_workshop --skip-interview
 ```
 
-This will create a new module `hue_workshop` in a directory of the same name, using all defaults. Output should look like the following:
+This command creates a new module `hue_workshop` in your directory of the same name, using all defaults. The output will look like:
 
 ```
 david@davids:~/tmp$ pdk new module hue_workshop --skip-interview
@@ -33,15 +33,15 @@ CHANGELOG.md  examples  Gemfile  hiera.yaml    metadata.json  README.md  tasks
 david@davids:~/tmp$
 ```
 
-To read more about the different options when creating new modules see [the PDK docs](https://puppet.com/docs/pdk/1.x/pdk_creating_modules.html).
+To read more about the different options when creating new modules, see [PDK docs](https://puppet.com/docs/pdk/1.x/pdk_creating_modules.html).
 
-Open the new directory in VSCode, or your coding editor of choice:
+Open the new directory in your code editor:
 
 ```
 code -a hue_workshop
 ```
 
-For this workshop, we'll active a few future defaults to make our lives easier down the line. Directly in the `hue_workshop` directory, create a file called `.sync.yml` and paste the following snippet:
+Next, we'll active a few future defaults. In the `hue_workshop` directory, create a file called `.sync.yml` and paste the following:
 
 ```
 # .sync.yml
@@ -56,7 +56,7 @@ spec/spec_helper.rb:
   mock_with: ':rspec'
 ```
 
-Then run `pdk update` in the module's directory to deploy the changes into the module:
+Run `pdk update` in the module's directory to deploy the changes in the module:
 
 ```
 david@davids:~/tmp/hue_workshop$ pdk update
@@ -82,4 +82,4 @@ david@davids:~/tmp/hue_workshop$
 
 ## Next up
 
-Once you have the module ready, head on to [add a transport](./04-adding-a-new-transport.md).
+Now that you have created a module, you'll [add a transport](./04-adding-a-new-transport.md).
diff --git a/docs/hands-on-lab/04-adding-a-new-transport.md b/docs/hands-on-lab/04-adding-a-new-transport.md
@@ -1,6 +1,6 @@
 # Add a new transport
 
-[Eventually](https://github.com/puppetlabs/pdk/pull/666) there will be a `pdk new transport`, for now you'll need to copy in a few files for this workshop.
+[Eventually](https://github.com/puppetlabs/pdk/pull/666) there will be a `pdk new transport` command. For now, you'll need to copy the files below.
 
 Copy the files from [this directory](./04-adding-a-new-transport/) into your new module:
 
@@ -11,7 +11,7 @@ Copy the files from [this directory](./04-adding-a-new-transport/) into your new
 * spec/unit/puppet/transport/hue_spec.rb
 * spec/unit/puppet/transport/schema/hue_spec.rb
 
-Afterwards run `pdk update --force` to enable a few future defaults that are required for these templates:
+Run `pdk update --force` to enable a few future defaults that are required for these templates:
 
 ```
 david@davids:~/tmp/hue$ pdk update --force
@@ -36,7 +36,7 @@ david@davids:~/tmp/hue$
 
 ## Checkpoint
 
-To make sure that everything went well with creating the module and copying in the files you can run `pdk validate --parallel` and `pdk test unit`:
+To validate your new module and transport, run `pdk validate --parallel` and `pdk test unit`:
 
 ```
 david@davids:~/tmp/hue$ pdk validate --parallel
@@ -62,7 +62,7 @@ Run options: exclude {:bolt=>true}
 david@davids:~/tmp/hue$
 ```
 
-If you're working with a version control system, this would also be a good point to make the first commit to store away all the boilerplate code and later revisit the changes you made. Here I'm showing how to initialise a local git repository and storing all files in an initial commit:
+If you're working with a version control system, now would be a good time to make your first commit and store the boilerplate code, and then you can revisit the changes you made later. For example: 
 
 ```
 david@davids:~/tmp/hue$ git init
@@ -102,4 +102,4 @@ david@davids:~/tmp/hue$
 
 ## Next up
 
-Once you have everything ready, head on to [implement the transport](./05-implementing-the-transport.md).
+Now that you have everything ready, you'll [implement the transport](./05-implementing-the-transport.md).
diff --git a/docs/hands-on-lab/05-implementing-the-transport-hints.md b/docs/hands-on-lab/05-implementing-the-transport-hints.md
@@ -1,18 +1,18 @@
 ## Implementing the transport - Exercise
 
-Implement a `request_debug` option that can be toggled on to create additional debug output on each request. You will not need concepts that you haven't yet seen in this tutorial, and basic programing skills. If you get stuck, have a look at some hints below, or [the finished file](TODO).
+Implement the `request_debug` option that you can toggle on to create additional debug output on each request. If you get stuck, review the hints below, or [the finished file](TODO).
 
 ## Hints
 
-* A toggle option can be created with the `Boolean` (`true` or `false`) data type. Add it to the `connection_info` in the transport schema.
+* You can create a toggle option with the `Boolean` (`true` or `false`) data type. Add it to the `connection_info` in the transport schema.
 
 * Make it an `Optional[Boolean]` so that users who do not require request debugging do not have to specify the value.
 
-* To remember the value passed in from the user, store `connection_info[:request_debug]` in a `@request_debug` variable.
+* To remember the value you passed, store `connection_info[:request_debug]` in a `@request_debug` variable.
 
-* In the `hue_get` and `hue_put` methods add `context.debug(message)` calls showing the method's arguments.
+* In the `hue_get` and `hue_put` methods, add `context.debug(message)` calls showing the method's arguments.
 
-* Make the debugging optional based on the user's input by appending `if @request_debug` to each logging statement.
+* Make the debugging optional based on your input by appending `if @request_debug` to each logging statement.
 
 # Next Up
 
diff --git a/docs/hands-on-lab/05-implementing-the-transport.md b/docs/hands-on-lab/05-implementing-the-transport.md
@@ -4,11 +4,11 @@ A transport consists of a *schema* describing the required data and credentials
 
 ## Schema
 
- The transport schema defines those attributes in a reusable manner, allowing users to understand the requirements of the transport. All schemas are located in `lib/puppet/transport/schema` in a ruby file named after the transport. In this case `hue.rb`.
+The transport schema defines attributes in a reusable way, allowing you to understand the requirements of the transport. All schemas are located in `lib/puppet/transport/schema` in a Ruby file named after the transport. In this case `hue.rb`.
 
-To connect to the HUE hub we need an IP address, a port, and an API key.
+To connect to the HUE hub you need an IP address, a port, and an API key.
 
-Replace the `connection_info` in `lib/puppet/transport/schema/hue.rb` with the following snippet.
+Replace the `connection_info` in `lib/puppet/transport/schema/hue.rb` with the following code:
 
 ```ruby
   connection_info: {
@@ -28,21 +28,21 @@ Replace the `connection_info` in `lib/puppet/transport/schema/hue.rb` with the f
   },
 ```
 
-> Note: The Resource API transports use [Puppet Data Types](https://puppet.com/docs/puppet/5.3/lang_data_type.html#core-data-types) to define the allowable values for an attribute. Abstract types like `Optional[]` can be useful to make using your transport easier. Take special note of the `sensitive: true` annotation on the `key`; it instructs all services processing this attribute with special care, for example to avoid logging the key.
+> Note: The Resource API transports use [Puppet Data Types](https://puppet.com/docs/puppet/5.3/lang_data_type.html#core-data-types) to define the allowable values for an attribute. Abstract types like `Optional[]` can be useful to make using your transport easier. Take note of the `sensitive: true` annotation on the `key`; it instructs all services processing this attribute with special care, for example to avoid logging the key.
 
 
 ## Implementation
 
-The implementation of a transport provides connectivity and utility functions for both puppet and the providers managing the remote target. The HUE API is a simple REST interface, so we can store the credentials until we need make a connection. The default template at `lib/puppet/transport/hue.rb` already does this. Have a look at the `initialize` function to see how this is done.
+The implementation of a transport provides connectivity and utility functions for both Puppet and the providers managing the remote target. The HUE API is a simple REST interface, so you can store the credentials until you need make a connection. The default template at `lib/puppet/transport/hue.rb` already does this. Have a look at the `initialize` function to see how this is done.
 
-For the HUE's REST API, we want to create a `Faraday` object to capture the target host and key, so the transport can facilitate requests. Replace the `initialize` method in `lib/puppet/transport/hue.rb` with the following snippet:
+For the HUE's REST API, we want to create a `Faraday` object to capture the target host and key so that the transport can facilitate requests. Replace the `initialize` method in `lib/puppet/transport/hue.rb` with the following code:
 
 <!-- TODO: do we really need this? -- probably not ```
     # @summary
     #   Expose the `Faraday` object connected to the hub
     attr_reader :connection
 
-``` -->
+```-->
 ```
     # @summary
     #   Initializes and returns a faraday connection to the given host
@@ -60,7 +60,7 @@ For the HUE's REST API, we want to create a `Faraday` object to capture the targ
 
 The transport is also responsible for collecting any facts from the remote target, similar to how facter works for regular systems. For now we'll only return a hardcoded `operatingsystem` value to mark HUE Hubs:
 
-Replace the example `facts` method in `lib/puppet/transport/hue.rb` with this snippet:
+Replace the example `facts` method in `lib/puppet/transport/hue.rb` with the following code:
 
 ```
     # @summary
@@ -70,13 +70,13 @@ Replace the example `facts` method in `lib/puppet/transport/hue.rb` with this sn
     end
 ```
 
-### Connection Verification and Closing
+### Connection verification and closing
 
 To enable better feedback when something goes wrong, a transport can implement a `verify` method to run extra checks on the credentials passed in.
 
 To save resources both on the target and the node running the transport, the `close` method will be called when the transport is not needed anymore. The transport can close connections and release memory and other resources at this point.
 
-For this tutorial, replace the example methods with this snippet:
+For this tutorial, replace the example methods with the following code:
 
 ```
     # @summary
@@ -93,9 +93,9 @@ For this tutorial, replace the example methods with this snippet:
 
 ### Making requests
 
-Besides exposing some standardises functionality to puppet, the transport is also a good place to put utility functions that can be reused across your providers. While it may seem overkill for this small example, it is no extra effort, and will establish a healthy pattern.
+Besides exposing some standardises functionality to Puppet, the transport is also a good place to put utility functions that can be reused across your providers. While it may seem overkill for this small example, it is no extra effort, and will establish a healthy pattern.
 
-Insert the following snippet after the `close` method:
+Insert the following code after the `close` method:
 
 ```
     # @summary
@@ -118,7 +118,7 @@ Insert the following snippet after the `close` method:
 
 ## Exercise
 
-Implement a `request_debug` option that can be toggled on to create additional debug output on each request. You will not need concepts that you haven't yet seen in this tutorial, and basic programing skills. If you get stuck, have a look at [some hints](./05-implementing-the-transport-hints.md), or [the finished file](TODO).
+Implement a `request_debug` option that you can toggle to create additional debug output on each request. If you get stuck, have a look at [some hints](./05-implementing-the-transport-hints.md), or [the finished file](TODO).
 
 
 # Next Up
diff --git a/docs/hands-on-lab/06-implementing-the-provider.md b/docs/hands-on-lab/06-implementing-the-provider.md
