diff --git a/docs/rolereference.rst b/docs/rolereference.rst
index a69fbe9d7e6d5148e994cff742dc78c988ed3279..04b87d3d456137b40d51976a56387c9ccf2bc972 100644
--- a/docs/rolereference.rst
+++ b/docs/rolereference.rst
@@ -227,11 +227,11 @@ The role implements the following:
 Parameters
 ~~~~~~~~~~
 
-**apt_proxy** (string, optional)
+**apt_proxy** (string, optional, ``None``)
   URI of a caching proxy that should be used when retrieving the packages via
-  apt. Default is no proxy.
+  apt.
 
-**os_users** (list, optional)
+**os_users** (list, optional, ``[]``)
   A list of operating system users that should be set-up on a server. Each item
   is a dictionary with the following options describing the user parameters:
 
@@ -239,50 +239,48 @@ Parameters
     Name of the operating system user that should be created. User's default
     group will have the same name as the user.
 
-  **uid** (number, mandatory)
+  **uid** (number, optional, ``whatever OS picks``)
     UID for the operating system user. User's default group will have a GID
-    identical to the user's UID.
+    identical to the user's UID if specified. Otherwise user's default group
+    will have OS-determined GID.
 
-  **additional_groups** (string, mandatory)
-    Comma-separated list of additional groups that a user should belong to. If
-    no additional groups should be appended to user's list of groups, set it to
-    empty string (``""``).
+  **additional_groups** (list, optional, ``[]``)
+    Comma-separated list of additional groups that a user should belong to.
 
-  **authorized_keys** (list, mandatory)
+  **authorized_keys** (list, optional, ``[]``)
     List of SSH public keys that should be deployed to user's authorized_keys
-    truststore. If no authorized keys should be deployed, set it to empty list
-    (``[]``).
+    truststore.
 
-  **password** (string, mandatory)
+  **password** (string, optional, ``!`` - no password)
     Encrypted password that should be set for the user.
 
-**os_groups** (list, optional)
+**os_groups** (list, optional, ``[]``)
   A list of operating system groups that should be set-up on a server. Each item
   is a dictionary with the following options describing the group parameters:
 
   **name** (string, mandatory)
     Name of the operating system group that should be created.
 
-  **gid** (number, mandatory)
+  **gid** (number, optional, ``whatever OS picks``)
     GID for the operating system group.
 
-**common_packages** (list, optional)
+**common_packages** (list, optional, ``[]``)
   List of additional operating system packages that should be installed on the
   server. Each element of the list should be a simple string denoting the name
   of the package.
 
-**ca_certificates** (list, optional)
+**ca_certificates** (list, optional, ``[]``)
   List of additional CA certificate files that should be deployed on the
   server. Each element of the list should be a filepath to a CA certificate file
   on originating (Ansible) host that should be copied to destination
   server.
 
-**incoming_connection_limit** (string, mandatory)
+**incoming_connection_limit** (string, optional, ``3/second``)
   Rate at which the incoming ICMP echo-request packages and new TCP connections
   will be accepted at. The value should be specified in the same format as value
   for the ``iptables hashlimit`` option ``--hashlimit-upto``.
 
-**incoming_connection_limit_burst** (string, mandatory)
+**incoming_connection_limit_burst** (string, optional, ``9``)
   Initial burst of packages that should be accepted when the client with
   distinct source IP address connects to the server for the first time (usually
   higher than ``incoming_connection_limit``), even if it would go above the
@@ -302,14 +300,13 @@ packages on all servers:
   os_users:
     - name: admin
       uid: 1000
-      additional_groups: sudo
+      additional_groups:
+        - sudo
       authorized_keys:
         - "{{ lookup('file', '/home/admin/.ssh/id_rsa.pub') }}"
       password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'
     - name: john
       uid: 1001
-      additional_groups: ""
-      authorized_keys: []
       password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'
 
   os_groups: