Icinga2 checks doc: improve phrasing, formatting, and fix some mistakes.

wiki/src/contribute/working_together/roles/sysadmins/adding_icinga2_checks.mdwn

@@ -14,27 +14,25 @@ new checks.
 
 # Plugins
 
-Icinga2 "plugins" are scripts or software executed by Icinga2 to
+Icinga2 *plugins* are scripts or software executed by Icinga2 to
 retrieve services data. Icinga2 natively ships a bunch of them. Have a
 look [at the
 documentation](http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/plugin-check-commands)
 if one fits our needs. If not, you'll have to install your custom
-plugin. Check the `tails::monitoring::plugin::check_torbrowser_archive`
-manifest in the [[!tails_gitweb_repo puppet-tails]] for a good
-example.
+plugin. Example: the `tails::monitoring::plugin::check_torbrowser_archive`
+class in [[!tails_gitweb_repo puppet-tails]].
 
-The plugins manifests are not deployed directly, but are rather
-included from their respective "check commands" manifests. See below.
+A plugin class is not included directly: instead, it is
+included from the corresponding *check command* class. See below.
 
 # Check commands
 
-"Check commands" are describing to Icinga2 the way to use plugins. It
+A *check command* tells Icinga2 how to use a plugin. It
 describes the options that can be used, and helps to configure for a
 service how this plugin will be executed. If you intend to use a new
-custom plugin, you also need to install the related check command. See
-the torbrowser-archive one for a good starter. See
-`tails::monitoring::checkcommand::torbrowser_archive` manifest in
-[[!tails_gitweb_repo puppet-tails]].
+custom plugin, you also need to install the related check command.
+Example: the `tails::monitoring::checkcommand::torbrowser_archive`
+class in [[!tails_gitweb_repo puppet-tails]].
 
 If you're using a new custom plugin, that's the place where you should
 include its manifest so that it is installed on every system for which a
@@ -42,42 +40,48 @@ service check is using it.
 
 # Services
 
-Once plugins and check commands are implemented, you can define a
-related service check.
+Once plugins and check commands are implemented, you can define the
+corresponding *service check*.
 
 Have a look at the `tails::monitoring::service::torbrowser_archive`
-manifest in [[!tails_gitweb_repo puppet-tails]] and the related service
+manifest in [[!tails_gitweb_repo puppet-tails]] and the corresponding service
 configuration template
 (`templates/monitoring/service/torbrowser_archive.erb` in the same repo).
-It is the place where the related check command manifest has to be
+It is the place where the corresponding check command class has to be
 included.
 
 There are two types of service checks:
 
 ## Remotely executed service
 
-Ran on the master to check a remotely hosted service. In this
-case, this service exported resources needs to be collected on the
-Icinga2 master only as we do in the `tails::monitoring::master` class
-for the `tails::monitoring::service::http` check in
-[[!tails_gitweb_repo puppet-tails]].
+Ran on the master to check a remotely hosted service. The exported
+resources for the service check need to be collected on the Icinga2
+master only. Example: the bits about the
+`tails::monitoring::service::http` check in the
+`tails::monitoring::master` class in [[!tails_gitweb_repo puppet-tails]].
 
 ## Locally executed service
 
-It needs to be deployed on every host that will run it.
-In this case, the exported resources for this kind of service checks
-need to be collected on the master, satellite and concerned system(s).
-That's what we do in the `tails::monitoring::{master,satellite,agent}`
-classes for the `tails::monitoring::service::memory` check in
+It needs to be deployed on every host that will run it. The exported
+resources for the service check need to be collected on the master,
+satellite and any system it should monitor.
+Example: the bits about the `tails::monitoring::service::memory` check
+in the `tails::monitoring::{master,satellite,agent}` classes in
 [[!tails_gitweb_repo puppet-tails]]. Make sure that the `$nodename` and
 `$tag` parameters are set when collecting such exported resources.
 
 # Deploy
 
-Once all of the plugin, check command and service related manifests are
-written, it's time to configure the service check. Declare it **as an
-exported resource** in the manifest of the node which hosts the service.
+Once the plugin, check command and service related manifests are
+written, it's time to enable the service check. Declare it *as an
+exported resource* in the manifest of the node which hosts the service.
 
-Depending if the service is local or remote, the Puppet clients may need
+Depending on whether the service is locally or remotely executed, the
+Puppet clients may need
 to be run several times on different systems for the service check
 exported resource to be collected and realized correctly.
+
+Once you've verified that the check works fine for one host,
+add it (if relevant) to the
+`tails::monitoring::config::common_services` class in
+[[!tails_gitweb_repo puppet-tails]].