(PDOC-33) Inform reader how to install yard gem

Also includes a variety of other README updates and modernizations.

README.md

@@ -2,11 +2,28 @@ Puppet Strings
 =============
 [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-strings.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-strings)
 
-A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and Puppet Future Parser.
+A Puppet Face and plugin built on the
+[YARD Documentation Tool](http://yardoc.org/) and the Puppet 4 Parser.
 It is uses YARD and the Puppet Parser to generate HTML documentation about
 Puppet code and Puppet extensions written in Ruby. It will eventually replace
 the `puppet doc` command once feature parity has been achieved.
 
+
+|                |                                                             |
+| -------------- |------------------------------------------------------------ |
+| *Code*         | [GitHub][repo]                                              |
+| *Issues*       | [Puppet Labs' JIRA Tracker][JIRA]                           |
+| *License*      | [Apache 2.0][LICENSE]                                       |
+| *Change log*   | [CHANGELOG.md][changelog]                                   |
+| *Contributing* | [CONTRIBUTING.md][changelog] and [COMMITTERS.md][committers]|
+
+[repo]: https://github.com/puppetlabs/puppetlabs-strings
+[JIRA]: https://tickets.puppetlabs.com/browse/PDOC
+[LICENSE]: https://github.com/puppetlabs/puppetlabs-strings/blob/master/LICENSE
+[changelog]: https://github.com/puppetlabs/puppetlabs-strings/blob/master/CHANGELOG.md
+[contributing]: https://github.com/puppetlabs/puppetlabs-strings/blob/master/CONTRIBUTING.md
+[committers]: https://github.com/puppetlabs/puppetlabs-strings/blob/master/COMMITTERS.md
+
 Installation
 ------------
 In order to run strings you need to have the following software installed:
@@ -15,48 +32,86 @@ In order to run strings you need to have the following software installed:
   * Puppet 3.7 or newer
   * The yard rubygem
 
-In order to install the strings module, simply `git clone` this repository into
+Install the yard rubygem with the gem command:
-your `modulepath` (i.e. `/etc/puppet/modules`). This module is also available
+
-on the [Puppet Forge](https://forge.puppetlabs.com/puppetlabs/strings) and can be installed with `puppet module install puppetlabs-strings`.
+```
+$ gem install yard
+```
+
+You may need to prefix this command with `bundle exec` or `sudo` depending on
+your ruby environment.
+
+Strings can be installed from the [Puppet Forge][forge strings] or from source.
+
+[forge strings]: https://forge.puppetlabs.com/puppetlabs/strings 
+
+**Installing from the Forge**
+
+Simply run this command and you're off to the races:
+
+```
+$ puppet module install puppetlabs-strings
+```
+
+**Installing from source**
+
+Simply `git clone` this repository into your `modulepath`
+(i.e. `/etc/puppet/modules`).
+
 
 Running Puppet Strings
------
+----------------------
-If you cloned the repository into your `modulepath` and installed the needed
-gems, you can do the following to document a module:
 
+Once strings has been installed you can document a puppet module:
+
+```
     $ cd /path/to/module
     $ puppet strings
+```
 
-This processes `README` and everything in `manifests/**/*.pp`.
+This processes `README` and all puppet and ruby files under `manifests/`
+and `lib/`.
 
-To document specific manifests:
+To document specific files:
 
-    $ puppet strings some_manifest.pp [another_if_you_feel_like_it.pp]
+```
+    $ puppet strings some_manifest.pp [another_if_you_feel_like_it.rb]
+```
 
-Processing is delegated to the `yardoc` tool so some options listed in `yard help doc` are available.
+Processing is delegated to the `yardoc` tool so some options listed in `yard
-However, Puppet Faces do not support passing arbitrary options through a face so these options must be specified in a `.yardopts` file.
+help doc` are available.  However, Puppet Faces do not support passing
+arbitrary options through a face so these options must be specified in a
+`.yardopts` file.
 
 In addition to generating a directory full of HTML, you can also serve up
 documentation for all your modules using the `server` action:
 
+```
     $ puppet strings server
+```
 
 Writing Compatible Documentation
------
+--------------------------------
-Since the strings module is built around YARD, a few different comment formats can be used.
-YARD can work with RDoc, meaning it is backwards compatible with previously documented modules.
-Feel free to try out strings with RDoc, but we are planning to move to Markdown as the standard.
-You can configure which you would like YARD to use by adding a `.yardopts` file to the root of
-your module directory which specifies the desired format:
 
+Since the strings module is built around YARD, a few different comment formats
+can be used.  YARD can work with RDoc, meaning it is backwards compatible with
+previously documented modules.  Feel free to try out strings with RDoc, but we
+are planning to move to Markdown as the standard.  You can configure which you
+would like YARD to use by adding a `.yardopts` file to the root of your module
+directory which specifies the desired format:
+
+```
     --markup markdown
+```
 
-While we have yet to decide exactly how documentation should work in the future, here are some
+While we have yet to decide exactly how documentation should work in the
-very basic examples to get you started using the strings module. These are very much subject
+future, here are some very basic examples to get you started using the strings
-to change as we continue to work out a style guide.
+module. These are very much subject to change as we continue to work out a
+style guide.
 
 Here's an example of how you might document a 4x function:
 
+```
      # When given two numbers, returns the one that is larger.
      # You could have a several line description here if you wanted,
      # but I don't have much to say about this function.
@@ -73,9 +128,11 @@ Here's an example of how you might document a 4x function:
          num_a >= num_b ? num_a : num_b
        end
      end
+```
 
 And here's an example of how you might document a class:
 
+```
      # This class is meant to serve as an example of how one might
      # want to document a manifest in a way that is compatible.
      # with the strings module
@@ -89,6 +146,7 @@ And here's an example of how you might document a class:
        $first_arg = $example::params::first_arg,
        $second_arg = $exampe::params::second_arg,
      ) { }
+```
 
 Here are a few other good resources for getting started with documentation:
 
@@ -96,9 +154,6 @@ Here are a few other good resources for getting started with documentation:
   * [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)
   * [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md)
 
-License
------
-See [LICENSE](https://github.com/puppetlabs/puppetlabs-strings/blob/master/LICENSE) file.
 
 Developing and Contributing
 -----
@@ -117,8 +172,7 @@ that you can run the spec tests. You should simply have to do the following:
 
 Support
 -----
-Please log tickets and issues at our [JIRA tracker](http://tickets.puppetlabs.com). The
+Please log tickets and issues at our [JIRA tracker][JIRA].
-puppet strings project can be found under [PDOC](https://tickets.puppetlabs.com/browse/PDOC) on JIRA.
 A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is
 available for asking questions and getting help from others. In addition there
 is an active #puppet channel on Freenode.
@@ -134,10 +188,13 @@ a best-effort basis, until the previous major version is no longer maintained.
 Caveats
 -------
 
-  - At the moment, only top-level Classes and Defined Types are parsed and formatted.
+  - At the moment, only top-level Classes and Defined Types are parsed and
+    formatted.
 
-  - Documentation blocks must immediately precede the documented code with no whitespace.
+  - Documentation blocks must immediately precede the documented code with no
-    This is because the comment extractor possesses the elegance and intelligence of a bag of hammers.
+    whitespace.  This is because the comment extractor possesses the elegance
+    and intelligence of a bag of hammers.
 
-  - This project is very much a work in progress and may very well have undiscovered bugs and pitfalls.
+  - This project is very much a work in progress and may very well have
-    If you discover any of these, [please file a ticket](https://tickets.puppetlabs.com/browse/PDOC).
+    undiscovered bugs and pitfalls. If you discover any of these,
+    [please file a ticket](https://tickets.puppetlabs.com/browse/PDOC).