doc: add instructions for using

2 files changed, 23 insertions, 1 deletions

diff --git a/roles/unix_users/subplot.md b/roles/unix_users/subplot.md
index f0acf36..78a7a48 100644
--- a/roles/unix_users/subplot.md
+++ b/roles/unix_users/subplot.md
@@ -1,4 +1,4 @@
-# unix_users – manage Unix users
+# Role `unix_users` – manage Unix users
 
 This role creates or updates Unix users.
 
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