improve docs

docs/general.md

@@ -1,30 +1,7 @@
 # Required variables
-These variables are required by some roles. Example values included.
+These variables might be required by multiple roles and need to be defined. Example values below.
 
 ```
 email: 'admin@domain.tld'
 ```
 
-# Default variables
-These variables have default values (shown below) which can be overridden.
-
-```
-install_packages:
-  - vim
-  - git
-  - etckeeper
-  - net-tools
-  - nmap
-  - ncdu
-  - fish
-  - parted
-```
-
-# Optional variables
-These variables are not required and not defined by default. Example values included.
-
-```
-delete_packages:
-  - nano
-  - curl
-```

docs/packages.md

@@ -0,0 +1,16 @@
+Installs packages defined in `install_packages` variable, which has the following defaults:
+
+```
+install_packages:
+  - vim
+  - git
+  - etckeeper
+  - net-tools
+  - nmap
+  - ncdu
+  - fish
+  - parted
+```
+
+Also deletes packages defined in `delete_packages` if defined
+

docs/users.md

@@ -0,0 +1,16 @@
+---
+
+Creates users specified in the `users` variable. Syntax:
+
+```
+users:
+  - name: username
+    password: hashed password
+    ssh_pubkey: 'ssh-rsa...'
+  - name: 'user1'
+    password: '$6$...'
+    ssh_pubkey: 'ssh-ed25519...'
+    shell: '/usr/bin/fish'
+```
+
+Specifying `shell` is optional