diff --git a/README.md b/README.md
index 7fc15d3..188024c 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,61 @@
 # devtools
 
-Installs tools for development on CI systems
+This role installs tools for development on CI systems
+
+This is used against the following types of systems:
+
+- Physical machines
+- Virtual machines (both cloud and on-prem)
+- Docker containers
+
+There are two sets of installed, one common set, and optional extended sets of
+tools.
+
+The default sets of tools are specified in the `tasks/main.yml` and
+`tasks/Debian.yml`. This contains basic development tools (git, make, python,
+repo, etc.) that are frequently used.
+
+The extended set of tools is dynamic and customizable, for projects that have
+individual tool requirements. These additional tools are specified using the
+`devtools_install` list which is loaded from `tasks/main.yml`. This list
+specifies filenames in the `tasks/` directory.
+
+## Adding a new development tool
+
+If you have a new tool (or set of tools) named `example`:
+
+1. Create a task file `tasks/example.yml`
+
+2. Add plays to the file to perform tool installation.
+
+   If required, add versions, download URLs, and SHA256 checksums for
+   downloaded files to the `defaults/main.yml`.  Prefix these variables with
+   `devtools_example_`
+
+3. Add Molecule tests for the tool to verify that it functions:
+
+   a. Add the installation to the `devtools_install` list in
+   `molecule/default/converge.yml`
+
+   b. Add tests to`molecule/default/verify.yml` that checks that the tools will
+   function correctly - mostly this would be running some variant of printing
+   the version, ie: `example --version` or similar, and verifying the version
+   number.
+
+Note that some tools that have more complicated installations, and in those
+cases a separate role should be created. One example of a more complicated tool
+that has it's own role is Docker, which requires a GPG key and apt repo,
+installs multiple tools, customizes it's configuration file, and so on.
 
 ## Example Playbook
 
 ```yaml
 - hosts: all
+  vars:
+    devtools_install:
+      - k8s
+      - terraform
+      - yq
   roles:
     - devtools
 ```