diff --git a/plugins/modules/floating_ip.py b/plugins/modules/floating_ip.py
index 77c976ed..a2dc1db4 100644
--- a/plugins/modules/floating_ip.py
+++ b/plugins/modules/floating_ip.py
@@ -8,11 +8,11 @@ DOCUMENTATION = '''
 ---
 module: floating_ip
 author: OpenStack Ansible SIG
-short_description: Add/Remove floating IP from an instance
+short_description: Manage floating IP addresses for OpenStack servers
 description:
-   - Add or Remove a floating IP to an instance.
-   - Returns the floating IP when attaching only if I(wait=true).
-   - When detaching a floating IP there might be a delay until an instance
+   - Add or remove an floating ip address to/from an OpenStack server.
+   - Returns the floating IP when attaching only if I(wait) is C(true).
+   - When detaching a floating IP there might be a delay until an server
      does not list the floating IP any more.
 options:
    fixed_address:
@@ -55,7 +55,7 @@ options:
      default: 'no'
    server:
      description:
-        - The name or ID of the instance to which the IP address
+        - The name or ID of the server to which the IP address
           should be assigned.
      required: true
      type: str
@@ -81,7 +81,7 @@ EXAMPLES = '''
      cloud: dguerri
      server: cattle001
 
-# Assign a new floating IP to the instance fixed ip `192.0.2.3` of
+# Assign a new floating IP to the server fixed ip `192.0.2.3` of
 # `cattle001`. If a free floating IP is already allocated to the project, it is
 # reused; if not, a new one is created.
 - openstack.cloud.floating_ip:
@@ -94,7 +94,7 @@ EXAMPLES = '''
      wait: true
      timeout: 180
 
-# Assign a new floating IP from the network `ext_net` to the instance fixed
+# Assign a new floating IP from the network `ext_net` to the server fixed
 # ip in network `private_net` of `cattle001`.
 - openstack.cloud.floating_ip:
      cloud: dguerri
@@ -376,7 +376,7 @@ class NetworkingFloatingIPModule(OpenStackModule):
                                                 floating_ip_id=ip['id'])
 
                 # OpenStackSDK sets {"port_id": None} to detach a floating
-                # ip from an instance, but there might be a delay until a
+                # ip from a device, but there might be a delay until a
                 # server does not list it in addresses any more.
                 changed = True
 
diff --git a/plugins/modules/server.py b/plugins/modules/server.py
index f058c922..85ea23c3 100644
--- a/plugins/modules/server.py
+++ b/plugins/modules/server.py
@@ -22,6 +22,10 @@ options:
           attach the server to a public network.
         - Requires I(wait) to be C(True) during server creation.
         - Floating IP support is unstable in this module, use with caution.
+        - Options I(auto_ip), I(floating_ip_pools) and I(floating_ips) interact
+          in non-obvious ways and undocumentable depth. For explicit and safe
+          attaching and detaching of floating ip addresses use module
+          I(openstack.cloud.resource) instead.
       type: bool
       default: 'yes'
       aliases: ['auto_floating_ip', 'public_ip']
@@ -91,6 +95,10 @@ options:
         - Name of floating IP pool from which to choose a floating IP.
         - Requires I(wait) to be C(True) during server creation.
         - Floating IP support is unstable in this module, use with caution.
+        - Options I(auto_ip), I(floating_ip_pools) and I(floating_ips) interact
+          in non-obvious ways and undocumentable depth. For explicit and safe
+          attaching and detaching of floating ip addresses use module
+          I(openstack.cloud.resource) instead.
       type: list
       elements: str
     floating_ips:
@@ -98,6 +106,10 @@ options:
         - list of valid floating IPs that pre-exist to assign to this node.
         - Requires I(wait) to be C(True) during server creation.
         - Floating IP support is unstable in this module, use with caution.
+        - Options I(auto_ip), I(floating_ip_pools) and I(floating_ips) interact
+          in non-obvious ways and undocumentable depth. For explicit and safe
+          attaching and detaching of floating ip addresses use module
+          I(openstack.cloud.resource) instead.
       type: list
       elements: str
     image: