Add documentation
Change-Id: I66572cae6d83f0dfacd3829358b345141b34d80f
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
```