Pivoted docs to generic resource{,s} modules and StateMachine class

Change-Id: Iebcd45d0eae79ab3911fd97c63d17b42d238f875

README.md

@@ -64,15 +64,15 @@ ansible-galaxy collection install -r requirements.yml
 
 ## Usage
 
-To use a module from the OpenStack Cloud collection, please reference the full namespace, collection name, and module
-name that you want to use:
+To use a module from the Ansible OpenStack collection, call them by their Fully Qualified Collection Name (FQCN),
+composed of their namespace, collection name and module name:
 
 ```yaml
 ---
-- name: Using OpenStack Cloud collection
-  hosts: localhost
+- hosts: localhost
   tasks:
-    - openstack.cloud.server:
+    - name: Create server in an OpenStack cloud
+      openstack.cloud.server:
         name: vm
         state: present
         cloud: openstack
@@ -87,12 +87,12 @@ Or you can add the full namespace and collection name in the `collections` eleme
 
 ```yaml
 ---
-- name: Using the Ansible OpenStack Collection
-  hosts: localhost
+- hosts: localhost
   collections:
     - openstack.cloud
   tasks:
-    - server_volume:
+    - name: Create server in an OpenStack cloud
+      server_volume:
         state: present
         cloud: openstack
         server: Mysql-server
@@ -100,6 +100,68 @@ Or you can add the full namespace and collection name in the `collections` eleme
         device: /dev/vdb
 ```
 
+For powerful generic [CRUD][crud]-style resource management use Ansible module
+[`openstack.cloud.resource`](plugins/modules/resource.py):
+
+```yaml
+---
+- hosts: localhost
+  tasks:
+    - name: Create security group
+      openstack.cloud.resource:
+        cloud: openstack
+        service: network
+        type: security_group
+        attributes:
+          name: ansible_security_group
+          description: 'ansible security group'
+
+    - name: Update security group description
+      openstack.cloud.resource:
+        cloud: openstack
+        service: network
+        type: security_group
+        attributes:
+          name: ansible_security_group
+          description: 'ansible neutron security group'
+
+    - name: Delete security group
+      openstack.cloud.resource:
+        cloud: openstack
+        service: network
+        type: security_group
+        attributes:
+          name: ansible_security_group
+        state: absent
+```
+
+For generic resource listing use Ansible module [`openstack.cloud.resources`](plugins/modules/resources.py):
+
+```yaml
+---
+- hosts: localhost
+  tasks:
+    - name: List images
+      openstack.cloud.resources:
+        cloud: openstack
+        service: image
+        type: image
+
+    - name: List compute flavors
+      openstack.cloud.resources:
+        cloud: openstack
+        service: compute
+        type: flavor
+
+    - name: List networks with name 'public'
+      openstack.cloud.resources:
+        cloud: openstack
+        service: network
+        type: network
+        parameters:
+          name: public
+```
+
 [Ansible module defaults][ansible-module-defaults] are supported as well:
 
 ```yaml
@@ -124,6 +186,7 @@ Or you can add the full namespace and collection name in the `collections` eleme
 ```
 
 [ansible-module-defaults]: https://docs.ansible.com/ansible/latest/user_guide/playbooks_module_defaults.html
+[crud]: https://en.wikipedia.org/wiki/CRUD
 
 ## Documentation
 

docs/contributing.md

@@ -24,14 +24,16 @@ openstacksdk], please read our [branching docs](branching.md).
 
 ## Examples
 
-* For an example on how to write a `*_info` module, have a look at module
-  [`openstack.cloud.neutron_rbac_policies_info`](../plugins/modules/neutron_rbac_policies_info.py).
+* For an example on how to write a `*_info` module, have a look at modules [`openstack.cloud.identity_role_info`](
+  ../plugins/modules/identity_role_info.py) or [`openstack.cloud.neutron_rbac_policies_info`](
+  ../plugins/modules/neutron_rbac_policies_info.py).
 * For an example on how to write a regular non-`*_info` module, have a look at module
-  [`openstack.cloud.neutron_rbac_policy`](../plugins/modules/neutron_rbac_policy.py) or any other module which
-  contains a `_will_change` method.
+  [`openstack.cloud.federation_idp`](../plugins/modules/federation_idp.py) or any other module which uses
+  [`class StateMachine`](../plugins/module_utils/resource.py).
 * Do NOT use modules which define a `_system_state_change` function as examples, because they often do not properly
-  define Ansible's check mode, idempotency and/or updates. Refer to modules which define a `_will_change` function
-  instead.
+  define Ansible's check mode, idempotency and/or updates. Refer to modules which use [`class StateMachine`](
+  ../plugins/module_utils/resource.py). In cases where using `class StateMachine` would cause code bloat, it might help
+  to look at modules which define a `_will_change` function instead.
 
 ## Naming