Clarify / update documentation to be in line with new wiki page.

README

@@ -1,7 +1,64 @@
-This is a blank repository you can use as a starting point for your
-local chef configuration.
+Overview
+========
 
-For full details on the parts aside from information contained in the
-README files, see the Chef wiki documentation at:
+Every Chef installation needs a Chef Repository. This is the place where cookbooks, roles, config files and other artifacts for managing systems with Chef will live. We strongly recommend storing this repository in a version control system such as Git and treat it like source code.
 
-http://wiki.opscode.com/display/chef/Chef+Repository
+While we prefer Git, and make this repository available via GitHub, you are welcome to download a tar or zip archive and use your favorite version control system to manage the code.
+
+Repository Directories
+======================
+
+This repository contains several directories, and each directory contains a README file that describes what it is for in greater detail, and how to use it for managing your systems with Chef.
+
+* `certificates/` - SSL certificates generated by `rake ssl_cert` live here.
+* `config/` - Contains the Rake configuration file, `rake.rb`.
+* `cookbooks/` - Cookbooks you download or create.
+* `data_bags/` - Store data bags and items in .json in the repository.
+* `roles/` - Store roles in .rb or .json in the repository.
+
+Rake Tasks
+==========
+
+The repository contains a `Rakefile` that includes tasks that are installed with the Chef libraries. To view the tasks available with in the repository with a brief description, run `rake -T`.
+
+The default task (`default`) is run when executing `rake` with no arguments. It will call the task `test_cookbooks`.
+
+The following tasks are not directly replaced by knife sub-commands.
+
+* `bundle_cookbook[cookbook]` - Creates cookbook tarballs in the `pkgs/` dir.
+* `install` - Calls `update`, `roles` and `upload_cookbooks` Rake tasks.
+* `ssl_cert` - Create self-signed SSL certificates in `certificates/` dir.
+* `update` - Update the repository from source control server, understands git and svn.
+
+The following tasks duplicate functionality from knife and may be removed in a future version of Chef.
+
+* `metadata` - replaced by `knife cookbook metadata -a`.
+* `new_cookbook` - replaced by `knife cookbook create`.
+* `role[role_name]` - replaced by `knife role from file`.
+* `roles` - iterates over the roles and uploads with `knife role from file`.
+* `test_cookbooks` - replaced by `knife cookbook test -a`.
+* `test_cookbook[cookbook]` - replaced by `knife cookbook test COOKBOOK`.
+* `upload_cookbooks` - replaced by `knife cookbook upload -a`.
+* `upload_cookbook[cookbook]` - replaced by `knife cookbook upload COOKBOOK`.
+
+Configuration
+=============
+
+The repository uses two configuration files.
+
+* config/rake.rb
+* .chef/knife.rb
+
+The first, `config/rake.rb` configures the Rakefile in two sections.
+
+* Constants used in the `ssl_cert` task for creating the certificates.
+* Constants that set the directory locations used in various tasks.
+
+If you use the `ssl_cert` task, change the values in the `config/rake.rb` file appropriately. These values were also used in the `new_cookbook` task, but that task is replaced by the `knife cookbook create` command which can be configured below.
+
+The second config file, `.chef/knife.rb` is a repository specific configuration file for knife. If you're using the Opscode Platform, you can download one for your organization from the management console. If you're using the Open Source Chef Server, you can generate a new one with `knife configure`. For more information about configuring Knife, see the Knife documentation.
+
+Next Steps
+==========
+
+Read the README file in each of the subdirectories for more information about what goes in those directories.

certificates/README

@@ -1,6 +1,19 @@
-Creating SSL certificates is a common task done in web application
-infrastructures, so a rake task is provided to generate certificates.
-These certificates are stored here by the ssl_cert task. To generate a
-certificate set for a new monitoring server, for example:
+Creating SSL certificates is a common task done in web application infrastructures, so a rake task is provided to generate certificates.  These certificates are stored here by the ssl_cert task.  
+
+Configure the values used in the SSL certificate by modifying `config/rake.rb`.
+
+To generate a certificate set for a new monitoring server, for example:
 
     rake ssl_cert FQDN=monitoring.example.com
+
+Once the certificates are generated, copy them into the cookbook(s) where you want to use them.
+
+    cp certificates/monitoring.example.com.* cookbooks/COOKBOOK/files/default
+
+In the recipe for that cookbook, create a `cookbook_file` resource to configure a resource that puts them in place on the destination server.
+
+    cookbook_file '/etc/apache2/ssl/monitoring.example.com.pem'
+      owner 'root'
+      group 'root'
+      mode 0600
+    end

cookbooks/README

@@ -1,2 +1,42 @@
-Download cookbooks into this directory from the Opscode Cookbooks site
-using knife, or remove this file to clone an upstream Git Repository.
+This directory contains the cookbooks used to configure systems in your infrastructure with Chef.
+
+Configure knife to use your preferred copyright holder, email contact and license. Add the following lines to `~/chef-repo/.chef/knife.rb`.
+
+    cookbook_copyright "Example, Com."
+    cookbook_email     "[email protected]"
+    cookbook_license   "apachev2"
+
+Supported values for `cookbook_license` are "apachev2" or "none". These settings are used to prefill comments in the default recipe, and the corresponding values in the metadata.rb. You are free to change these in those files.
+
+Create new cookbooks in this directory with Knife.
+
+    knife cookbook create COOKBOOK
+
+This will create all the cookbook directory components. You don't need to use them all, and can delete the ones you don't need. It also creates a README file, metadata.rb and default recipe.
+
+You can also download cookbooks directly from the Opscode Cookbook Site. There are two subcommands to help with this depending on what your preference is.
+
+The first and recommended method is to use a vendor branch if you're using Git. This is automatically handled with Knife.
+
+    knife cookbook site vendor COOKBOOK
+
+This will:
+
+* Download the cookbook tarball from cookbooks.opscode.com.
+* Ensure its on the git master branch.
+* Checks for an existing vendor branch, and creates if it doesn't.
+* Checks out the vendor branch (chef-vendor-COOKBOOK).
+* Removes the existing (old) version.
+* Untars the cookbook tarball it downloaded in the first step.
+* Adds the cookbook files to the git index and commits.
+* Creates a tag for the version downloaded.
+* Checks out the master branch again.
+* Merges the cookbook into master.
+
+The last step will ensure that any local changes or modifications you have made to the cookbook are preserved, so you can keep your changes through upstream updates.
+
+If you're not using Git, use the site download subcommand to download the tarball.
+
+    knife cookbook site download COOKBOOK
+
+This creates the COOKBOOK.tar.gz from in the current directory (e.g., `~/chef-repo`). We recommend following a workflow similar to the above for your version control tool.

data_bags/README

@@ -1,21 +1,23 @@
-First, create the data bag. Name it whatever you want.
+This directory contains directories of the various data bags you create for your infrastructure. Each subdirectory corresponds to a data bag on the Chef Server, and contains JSON files of the items that go in the bag.
 
-    knife data bag create BAG
+First, create a directory for the data bag.
+
+    mkdir data_bags/BAG
 
-Next, create data bag JSON files in subdirectories by data bag name. Then
-upload the items to the Chef Server with knife:
+Then create the JSON files for items that will go into that bag.
 
-    knife data bag from file BAG FILE
+    $EDITOR data_bags/BAG/ITEM.json
 
-For example, create a bag named 'apps' with an item named 'instiki':
+The JSON for the ITEM must contain a key named "id" with a value equal to "ITEM". For example,
 
-    mkdir data_bags/apps
-    echo '{ "id": "instiki" }' > data_bags/apps/instiki.json
+    {
+      "id": "foo"
+    }
 
-Then upload it to the server:
+Next, create the data bag on the Chef Server.
 
-    knife data bag from file apps instiki.json
+    knife data bag create BAG
 
-For more information about data bags, see the Chef wiki.
+Then upload the items in the data bag's directory to the Chef Server.
 
-http://wiki.opscode.com/display/chef/Data+Bags
+    knife data bag from file BAG ITEM.json

roles/README

@@ -1,14 +1,13 @@
-Create roles here, in either .rb or .json files. To install roles on the
-server, use knife. For example, create roles/base_example.rb:
+Create roles here, in either the Role Ruby DSL (.rb) or JSON (.json) files. To install roles on the server, use knife.
+
+For example, create `roles/base_example.rb`:
 
     name "base_example"
     description "Example base role applied to all nodes."
     # List of recipes and roles to apply. Requires Chef 0.8, earlier versions use 'recipes()'.
     #run_list()
-
     # Attributes applied if the node doesn't have it set already.
     #default_attributes()
-
     # Attributes applied no matter what the node has set already.
     #override_attributes()