doc: add instructions for using

1 files changed, 22 insertions, 0 deletions

diff --git a/subplot.md b/subplot.md
index ae7fbb0..4581174 100644
--- a/subplot.md
+++ b/subplot.md
@@ -11,6 +11,28 @@ as intended.
 
 [Subplot]: https://subplot.liw.fi/
 
+## Using these roles
+
+Eventually, all the roles included with `debian-ansible` will follow
+the same principles:
+
+* the playbook using a role defines which version of each role they
+  expect to use by defining a variable such as `unix_users_version`
+  - the role checks that it's defined to the right value and fails if
+    it isn't
+* the role is parameterized via variables, with names prefixed with
+  the role name
+  - the role `unix_users` expects a variable `unix_users` that lists
+    all the users to create
+* any variables used by role have "empty" default values, unless the
+  variable must be defined by the playbook using the role
+  - the role will check that the necessary variables are defined,
+    before doing anything
+
+# Implementation and testing of these roles
+
+If you're just using the roles, you don't need to care about this chapter.
+
 ## Source files
 
 At the root of the `debian-ansible` source tree is a `subplot.md`, and