DOC-2127: Implement edits by @kayayarai.

Major post and major agent upgrade docs.

source/puppet/4.2/reference/upgrade_major_agent.markdown

@@ -10,95 +10,97 @@ canonical: "/puppet/latest/reference/upgrade_major_agent.html"
 [moved]: ./whered_it_go.html
 [facter]: /facter/
 
-Although there are a lot of changes to Puppet agent configuration in Puppet 4, the process of upgrading agents can be automated in a way that server upgrades can't.
+Although there are a lot of changes to Puppet Agent configuration in Puppet 4, the process of upgrading agents can be automated in a way that server upgrades can't.
 
 ## Decide How to Upgrade Your Nodes
 
 We provide a module called [`puppet_agent`][puppet_agent] to simplify upgrades from Puppet 3 to 4.
 
-If you're running Puppet on Windows or [any supported Linux operating system](./system_requirements.html#platforms-with-packages), this module can automatically upgrade Puppet, MCollective, and all of their dependencies on agent nodes.
+If you're running Puppet on Windows or [any supported Linux operating system](./system_requirements.html#platforms-with-packages), this module can automatically upgrade Puppet, MCollective, and all of their dependencies on agents.
 
-If you're running Puppet on other operating systems, you can't upgrade them with the module. You'll need to either upgrade your agents manually or automate the process yourself.
+If you're running Puppet on other operating systems, you can't upgrade them with the module. You can either upgrade your agents manually or automate the process yourself.
 
 This document guides you step-by-step through both methods.
 
 ## Upgrade with the `puppet_agent` Module
 
-> **Note**: This module only works on Windows and supported Linux distributions. If your agents run any other operating systems, skip to ["Upgrade Manually or Build Your Own Automation"](#upgrade-manually-or-build-your-own-automation).
+> **Note**: This module works on Windows and supported Linux distributions. If your agents run any other operating systems, skip to ["Upgrade Manually or Build Your Own Automation"](#upgrade-manually-or-build-your-own-automation).
 
 The `puppet_agent` module does the following things for you:
 
-- Enables the Puppet Collection 1 (PC1) repo, if applicable.
+- Enables the Puppet Collection 1 (PC1) repository, if applicable.
 - Installs the latest version of the `puppet-agent` package, which replaces the installed versions of Puppet, [Facter][], [Hiera][], and [MCollective][].
 - Copies Puppet's SSL files to their new location.
-- Copies your old `puppet.conf` to Puppet 4's [new location](https://docs.puppetlabs.com/puppet/4.0/reference/whered_it_go.html), then cleans out old settings that we either removed in Puppet 4 or needed to revert to their default values.
+- Copies your old `puppet.conf` to Puppet 4's [new location](https://docs.puppetlabs.com/puppet/4.0/reference/whered_it_go.html), and cleans out old settings that we either removed in Puppet 4 or needed to revert to their default values.
 - Copies your MCollective server and client configuration files to their new locations, and adds [the new plugin path](/mcollective/deploy/plugins.html) to the `libdir` setting.
 - Ensures the Puppet and MCollective services are running.
 
-`puppet_agent` is completely inert on nodes already running Puppet 4---its only purpose is to help you upgrade from Puppet 3.
+The `puppet_agent`  module is completely inert on nodes already running Puppet 4---its only purpose is to help you upgrade from Puppet 3.
 
 ### Install the Module on Puppet Servers
 
-* If you manage your Puppet code manually, you can use install it with `puppet module install puppetlabs/puppet_agent --environment <ENVIRONMENT>`
+* If you manage your Puppet code manually, install it by running `puppet module install puppetlabs/puppet_agent --environment <ENVIRONMENT>`
 * If you manage your code with [r10k](/pe/latest/r10k.html), add the module and its dependencies to your Puppetfile.
 * If you manage your code some other way, install `puppet_agent` as you would any other module.
 
 ### Assign the `puppet_agent` Class to Nodes
 
-However you classify nodes---whether in the [main mainfest](./dirs_manifest.html), with an [external node classifier](/guides/external_nodes.html) or [Hiera][], or some other solution---remember to classify your agents with `puppet_agent`.
+However you classify nodes---whether in the [main mainfest](./dirs_manifest.html), with an [external node classifier](/guides/external_nodes.html) or [Hiera][], or some other  method---classify your agents with `puppet_agent`.
 
 You can also [configure the module](https://forge.puppetlabs.com/puppetlabs/puppet_agent/readme#usage) to control which services start or to force a different architecture on Windows.
 
-As with any major configuration change, carefully control and monitor the rollout. Assign the class in a dev or test environment to ensure it works as expected on systems similar to your production environment, then roll it out to your live agents in phases and monitor the upgraded agents for issues.
+As with any major configuration change, carefully control and monitor the rollout. Assign the class in a development or test environment to ensure it works as expected on systems similar to your production environment. Roll it out to your live agents in phases, and monitor the upgraded agents for issues.
 
 ### Post-Upgrade Clean-Up
 
-After you've upgraded your entire deployment, you should read our suggested [post-upgrade clean-up tasks](./upgrade_major_post.html).
+After you've upgraded your entire deployment, do the [post-upgrade clean-up tasks](./upgrade_major_post.html).
 
 ## Upgrade Manually or Build your Own Automation
 
-To upgrade agents without the `puppet_agent` module, you can either install the upgrades manually or design your own upgrade automation.
+To upgrade agents without using the `puppet_agent` module, you can either install the upgrades manually or design your own upgrade automation.
 
 ### Install the New Version of Puppet
 
-Follow the installation instructions; find your OS in the sidebar navigation to the left, or do whatever you originally did to install Puppet.
+Find your operating system in the sidebar navigation to the left and follow the Puppet Agent installation instructions.
 
 ### Move SSL Files (\*nix Only)
 
 On \*nix systems, we [moved][] the default [`confdir`](./dirs_confdir.html) to `/etc/puppetlabs/puppet` in Puppet 4. Since the default [`ssldir`](./dirs_ssldir.html) is `$confdir/ssl`, its location changes during the upgrade.
 
 In Puppet 3, the default `ssldir` is `/etc/puppet/ssl`; some systems might also use  `/var/lib/puppet/ssl`.
 
-Locate your [`ssldir`](./dirs_ssldir.html) in `/etc/puppet/puppet.conf`, then move that directory's contents to `/etc/puppetlabs/puppet/ssl` without changing the files' permissions:
+Locate your [`ssldir`](./dirs_ssldir.html) in `/etc/puppet/puppet.conf` and move that directory's contents to `/etc/puppetlabs/puppet/ssl` without changing the files' permissions. For example, run:
 
-`cp -rp /var/lib/puppet/ssl /etc/puppetlabs/puppet/ssl`
+~~~ bash
+# cp -rp /var/lib/puppet/ssl /etc/puppetlabs/puppet/ssl
+~~~
 
 ### Reconcile `puppet.conf`
 
-On \*nix systems, we [moved][] [`puppet.conf`](./config_file_main.html) from `/etc/puppet/puppet.conf` to `/etc/puppetlabs/puppet/puppet.conf`. You need to either edit the new `puppet.conf` file or copy your old version. (We didn't change `puppet.conf`'s location on Windows.)
+On \*nix systems, we [moved][] [`puppet.conf`](./config_file_main.html) from `/etc/puppet/puppet.conf` to `/etc/puppetlabs/puppet/puppet.conf`. Either edit the new `puppet.conf` file or copy your old version. (We didn't change `puppet.conf`'s location on Windows.)
 
 Examine the new `puppet.conf` regardless of your operating system and confirm that:
 
 * It includes any necessary modifications.
-* It excludes any settings that were [removed in Puppet 4.0](/puppet/3.8/reference/deprecated_settings.html). Notably, if you set `stringify_facts=false` [before upgrading](./upgrade_major_pre.html), you can remove this setting.
+* It excludes any settings that were [removed in Puppet 4.0](/puppet/3.8/reference/deprecated_settings.html). Notably, if you set `stringify_facts=false` [before upgrading](./upgrade_major_pre.html), remove this setting.
 * All [important settings](./config_important_settings.html#settings-for-puppet-master-servers) are correctly configured for your site.
 
 ### Start Service or Update Cron Job
 
-We also [moved][] Puppet binaries to `/opt/puppetlabs/bin` in Puppet 4. If you run Puppet as a service, it should be configured to launch at boot using `/opt/puppetlabs/bin/puppet resource`:
+We also [moved][] Puppet binaries to `/opt/puppetlabs/bin` in Puppet 4. If you run Puppet as a service, configure it to launch at boot using `/opt/puppetlabs/bin/puppet resource`:
 
 `/opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true`
 
-On Windows, you can use the same command but omit the `/opt/puppetlabs/bin/` prefix.
+On Windows, use the same command but omit the `/opt/puppetlabs/bin/` prefix.
 
 If you use a cron job to periodically run `puppet agent -t` on your \*nix systems, edit the job and update the `puppet` binary's path to `/opt/puppetlabs/bin/puppet`.
 
 ### Reconcile MCollective Config Files (\*nix Only)
 
 On \*nix systems, we [moved][] MCollective's configuration files from `/etc/mcollective` to `/etc/puppetlabs/mcollective`.
 
-Edit the new configuration files to port over any settings you need from the old configuration files. Note that the default plugin and library directories also changed; you should update your settings to use both the new directories and any other directories you wish to use.
+Edit the new configuration files to port over any settings you need from the old configuration files. The default plugin and library directories also changed; update your settings to use the new directories and any other directories you wish to use.
 
 ### Post-Upgrade Clean-Up
 
-After you've upgraded your entire deployment, you should read our suggested [post-upgrade clean-up tasks](./upgrade_major_post.html).
+After you've upgraded your entire deployment, do the [post-upgrade clean-up tasks](./upgrade_major_post.html).

source/puppet/4.2/reference/upgrade_major_post.md

@@ -6,24 +6,24 @@ canonical: "/puppet/latest/reference/upgrade_major_post.html"
 
 [moved]: ./whered_it_go.html
 
-After upgrading, you should do a few more things to make Puppet 4 more stable and easier to maintain.
+After upgrading, you should do a few more things to make Puppet 4 easier to maintain.
 
 ## Reconfigure Systems that Use Puppet's Data
 
-Puppet 4 [changes the locations of many configuration files][moved]. If you have any other systems that reuse Puppet's SSL credentials, configuration data, or generated data, remember to point them to the new directories.
+Puppet 4 [changes the locations of many configuration files][moved]. If you have any other systems that reuse Puppet's SSL credentials, configuration data, or generated data, point them to the new directories.
 
 ## Update Backup Jobs
 
 If you back up data in directories that [moved][] (like `/etc/puppet`, whose contents are now split between `/etc/puppetlabs/puppet` and `/etc/puppetlabs/code`), update your backup jobs to use the new locations.
 
 ## Delete the `/etc/puppet` Directory on \*nix Systems
 
-You can avoid maintenance and configuration confusion by deleting the old `/etc/puppet` directory on your \*nix systems. This prevents other systems from using stale data and protects sysadmins from accidentally updating the wrong copies of files.
+Avoid maintenance and configuration confusion by deleting the old `/etc/puppet` directory on your \*nix systems. This prevents other systems from using stale data and protects sysadmins from accidentally updating the wrong copies of files.
 
 ## Delete the Per-Environment `parser` Setting
 
 If you set the [`parser`](/puppet/3.8/reference/config_file_environment.html#parser) setting in `environment.conf` as part of your [upgrade preparations](./upgrade_major_pre.html), remove it from all environments. The setting is  inert, but Puppet will log warnings until it's gone.
 
 ## Unassign `puppet_agent` Class from Nodes
 
-The [`puppet_agent` module](https://forge.puppetlabs.com/puppetlabs/puppet_agent) doesn't affect nodes running Puppet 4, and you can unassign it from all nodes once your entire Puppet infrastructure is upgraded.
+The [`puppet_agent` module](https://forge.puppetlabs.com/puppetlabs/puppet_agent) doesn't affect nodes running Puppet 4, and you can unassign it from all nodes after your entire Puppet infrastructure is upgraded.