From 97af892cc2f121839d89167919c1817177fe637a Mon Sep 17 00:00:00 2001
From: Gary Larizza <gary@puppetlabs.com>
Date: Tue, 9 Oct 2012 20:11:48 -0700
Subject: [PATCH] Update README

Previously, documentation around creating modules and using site.pp
was pretty slim. This commit adds more documentation and links to
Puppet's documentation site.
---
 README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 46 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 7491ee5..6316c9a 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,46 @@ You can always check out the number of existing modules we already
 provide as optional installs under the
 [boxen organization](https://github.com/boxen). These modules are all
 tested to be compatible with Boxen. Use the `Puppetfile` to pull them
-in dependencies automatically whenever `boxen` is run. You'll have to
+in dependencies automatically whenever `boxen` is run. 
+
+### Node Definitions ###
+
+Puppet has the concept of a ['node'](http://docs.puppetlabs.com/references/glossary.html#agent), which is essentially the machine on which Puppet is running. Puppet looks for [node definitions](http://docs.puppetlabs.com/learning/agent_master_basic.html#node-definitions) in the `manifests/site.pp` file in the Boxen repo. You'll see a default node declaration that looks like the following:
+
+    node default {
+      # core modules, needed for most things
+      include dnsmasq
+      <...>
+    }
+
+All Puppet [class declarations](http://docs.puppetlabs.com/learning/modules1.html#classes) should be included in the default node definition.  Theoretically, you _COULD_ declare every [Puppet resource](http://docs.puppetlabs.com/learning/ral.html) in the `manifests/site.pp` file, but that would quickly become unwieldy. Instead, it's easier to create [Puppet modules](http://docs.puppetlabs.com/learning/modules1.html#modules) inside the `modules` folder of the Boxen repo. Boxen is setup to discover any modules you create in the `modules` folder, and we've already created a `people` and `projects` module structure for you to start using.
+
+### Creating a personal module ###
+
+Using the `modules/people` folder that's been provided in the Boxen repo, start by creating a file in `modules/people/manifests` in the format of `your_last_name.pp` (Feel free to use the [Puppet module cheat sheet](http://docs.puppetlabs.com/module_cheat_sheet.pdf) if you need some extra help). If we were making a module for [Tim Sharpe](http://github.com/rodjek), we would create a file called `modules/people/manifests/sharpe.pp` that would look like the following:
+
+    # modules/people/manifests/sharpe.pp
+    class people::sharpe {
+      # Resource Declarations go here
+      package { 'tree':
+        ensure   => installed,
+        provider => homebrew,
+      }
+    }
+
+This class is installing the `tree` package out of
+[Homebrew](https://github.com/mxcl/homebrew), but feel free to add whatever
+resource declarations you'll need.  Finally, add the following line in the
+`manifests/site.pp` file within the default node definition:
+
+    include people::sharpe
+
+Finally, run `boxen --noop` to [simulate, or
+test](http://docs.puppetlabs.com/guides/tests_smoke.html#running-tests) what
+changes your code would have made. If you're happy with how things look, you
+can then run `boxen` to enforce the changes you've made
+
+You'll have to
 make sure your "node" (Puppet's term for your laptop, basically)
 includes or requires them. You can do this by either modifying
 `manifests/site.pp` for each module, _or_ we would generally recommend
@@ -73,9 +112,13 @@ create an environment class in that. Then you need only adjust
 `manifests/site.pp` by doing `include github::environment` or
 what-have-you for your organization.
 
-For organization projects (read: repositories that people will be working in), please see the documentation in the projects module template we provide.
+### Creating a project module ###
 
-For per-user configuration that doesn't need to be applied globally to everyone, please see the documentation in the people module template we provide.
+The `modules/projects` folder is provided for organizational projects that
+aren't specific to one person. You're free to create any number of modules in
+the `modules` directory. As long as you follow Puppet's module naming patterns,
+everything should be fine. For more information, see the documentation in the
+projects module template that we provide.
 
 ## Binary packages