Merge lp:~nextrevision/charms/precise/puppet/updated-charm-readme into lp:charms/puppet

[John Patterson]

Renamed the README file to README.md; added Markdown syntax; added project description; added a bit more description to various sections.

[Marco Ceppi (marcoceppi)]

Hi John, thanks for fixing up the readme, however it looks like this merge proposal is a little backwards. No big deal you'll just want to resubmit it proposing your branch to be merged in to lp:charms/puppet.

review: Needs Resubmitting

[John Patterson (nextrevision)]

Doh! Thanks for pointing that out, I thought something looked off. It has been resubmitted.

[Marco Ceppi (marcoceppi)]

LGTM +1

review: Approve

=== renamed file 'README' => 'README.md'
--- README	2012-04-16 17:10:00 +0000
+++ README.md	2013-05-23 01:35:35 +0000
@@ -1,36 +1,58 @@
+# Overview
+
 This subordinate charm can be used to apply system level policy on top
-of any juju charms deployed, using puppet.
-
-In order to deploy on top of the wordpress+mysql example:
-
-# This should give you wordpress:
-
-juju deploy wordpress
-juju deploy mysql
-juju add-relation mysql wordpress
-
-# Now add puppet to wordpress and mysql
-
-juju deploy puppet
-juju add-relation puppet wordpress
-juju add-relation puppet mysql
-
-#If you have an external puppet master, note that you will have to use
-#some method to classify nodes automatically.  The yaml from 'juju status'
-#should be parsable into an external node classifier.
-
-juju set puppet external-puppetmaster=puppet.yourdomain.com
-
-# If you need puppet set up:
-
-juju deploy puppetmaster
-# ... setup puppet classes 'mysql' and 'wordpress'
-juju ssh puppetmaster/0
-# This next command will result in all nodes being put into a class
-# that is named after their primary service, so the example will have,
-# as suggested, two classes, mysql and wordpress.
-juju add-relation puppetmaster:puppetmaster puppet:puppetmaster
-
-That should end up with puppet agent running on the wordpress and
-mysql nodes, pointed at either your external puppetmaster, or the
+of any Juju charms deployed, using Puppet. As described by the project
+[website](https://puppetlabs.com/):
+
+> Puppet Open Source is a flexible, customizable framework available under
+> the Apache 2.0 license designed to help system administrators automate the
+> many repetitive tasks they regularly perform. As a declarative, model-based
+> approach to IT automation, it lets you define the desired state - or the
+> "what" - of your infrastructure using the Puppet configuration language.
+
+# Usage
+
+This example will show how to deploy puppet on top of the WordPress+MySQL example.
+
+## Installing WordPress and MySQL
+
+    juju deploy wordpress
+    juju deploy mysql
+    juju add-relation mysql wordpress
+
+## Adding Puppet to WordPress and MySQL
+
+    juju deploy puppet
+    juju add-relation puppet wordpress
+    juju add-relation puppet mysql
+
+## Specifying an external puppetmaster
+
+If you have an external puppetmaster, note that you will have to use
+some method to classify nodes automatically.  The yaml from 'juju status'
+should be parsable into an external node classifier.
+
+    juju set puppet external-puppetmaster=puppet.yourdomain.com
+
+# Setting up and configuring a puppetmaster
+
+For environments without an existing puppetmaster, first deploy a new one:
+
+    juju deploy puppetmaster
+
+Next, you will need to setup Puppet classes 'mysql' and 'wordpress':
+
+    juju ssh puppetmaster/0
+
+This next command will result in all nodes being put into a class
+that is named after their primary service, so the example will have,
+as suggested, two classes, 'mysql' and 'wordpress'.
+
+    juju add-relation puppetmaster:puppetmaster puppet:puppetmaster
+
+# Conclusion
+
+That should end up with puppet agent running on the WordPress and
+MySQL nodes, pointed at either your external puppetmaster, or the
 newly deployed puppetmaster.
+