diff --git a/changelogs/fragments/oraswgi_install.yml b/changelogs/fragments/oraswgi_install.yml
new file mode 100644
index 000000000..eb1c1d9fc
--- /dev/null
+++ b/changelogs/fragments/oraswgi_install.yml
@@ -0,0 +1,3 @@
+---
+bugfixes:
+  - "oraswgi_install: documentation changes for ansible-doctor make happy again (oravirt#474)"
diff --git a/doc/guides/restart_rac.adoc b/doc/guides/restart_rac.adoc
new file mode 100644
index 000000000..87aa19d1b
--- /dev/null
+++ b/doc/guides/restart_rac.adoc
@@ -0,0 +1,63 @@
+:toc:
+:toc-placement!:
+:toclevels: 4
+toc::[]
+
+:sectnums:
+:sectnumlevels: 4
+
+== Setup ASM for Oracle Grid Infrastructure / Restart
+
+.Inventory Variables for ASM
+[options="header,footer"]
+|=======================
+|Value |Default |Description
+|`device_persistence`
+|empty string
+| Allowed values: `asmfd`, `asmlib`
+|`oracle_asm_disk_string`
+|`ORCL:*`
+| init.ora-Parameter for `asm_diskstring`.
+|`oracle_asm_init_dg`
+|`crs`
+| 1st Diskgroup for ASM SPFile.
+|`asm_diskgroups`
+|
+| Defines the ASM-Diskgroups. More Details below.
+|=======================
+
+.Example `asm_diskgroups`
+----
+asm_diskgroups:        # ASM Diskgroups used for DB-storage. Should map to dict asm_storage_layout.
+  - diskgroup: data
+    state: present
+    properties:
+      - {redundancy: external, ausize: 4}
+    attributes:
+      - {name: compatible.rdbms, value: 11.2.0.4.0}
+      - {name: compatible.asm, value: "19.0.0.0.0"}
+    disk:
+      - {device: /dev/sdc, asmlabel: data01}
+----
+
+== Setup Real Application Clusters (RAC)
+
+IMPORTANT: The documentation is heavily work in progress.
+
+=== Inventory Variables
+
+.Inventory Variables for Cluster configuration
+[options="header,footer"]
+|=======================
+|Value |Default |Description
+|`oracle_install_option_gi`
+|empty string
+| Allowed values: `CRS_CONFIG`, `HA_CONFIG`
+| `oracle_node_vip`
+| {{ ansible_hostname }}{{ oracle_vip }}
+| Defines the VIP of the clusternode.
+| `oracle_vip`
+| `-vip`
+| Suffix for VIP when `oracle_node_vip` is not defined.
+|=======================
+
diff --git a/roles/oraswgi_install/README.md b/roles/oraswgi_install/README.md
index 5f269ee74..49ffa2582 100644
--- a/roles/oraswgi_install/README.md
+++ b/roles/oraswgi_install/README.md
@@ -99,8 +99,7 @@ gi_ignoreprereq: false
 
 ### oracle_asm_init_dg
 
-Do not use - is replaced in the future!
-Reason why RAC support has been disabled...
+1st Diskgroup where ASM SPFile is placed.
 
 #### Default value
 
@@ -190,8 +189,11 @@ oracle_gi_nic_pub: eth0
 
 ### oracle_ic_net
 
-Do not use - is replaced in the future!
-Reason why RAC support has been disabled...
+Defines the network for the interconnect.
+
+Important!
+
+Only used, when `configure_interconnect=true` and `ansible_os_family='RedHat'` during cluster installations.
 
 #### Default value
 
@@ -231,7 +233,13 @@ oracle_sw_image_gi:
 
 suffix added to hostnames for VIPs.
 
-hostnamea{{ oracle_vip }}
+{{ ansible_hostname }}{{ oracle_vip }}
+
+Important!
+
+`oracle_node_vip` defines a fixed hostname for the VIP.
+
+That replaces the logic from `oracle_vip` for the VIP!
 
 #### Default value
 
@@ -293,8 +301,6 @@ run_configtoolallcommand: true
 
 ## Open Tasks
 
-- (bug): oracle_vip is not flexible enough.
-- (bug): oracle_ic_net will be removed in the future
 - (bug): ConfigTools should not depend on olr.loc...
 - (bug): ConfigTools should not depend on olr.loc...
 - (information): add selectattr to asm_diskgroups
diff --git a/roles/oraswgi_install/defaults/main.yml b/roles/oraswgi_install/defaults/main.yml
index 50cb946ce..5fc8686d5 100644
--- a/roles/oraswgi_install/defaults/main.yml
+++ b/roles/oraswgi_install/defaults/main.yml
@@ -23,11 +23,16 @@ default_dbpass: "{% if item.0.oracle_db_passwd is defined %}{{ item.0.oracle_db_
 # @end
 # oracle_scan:
 
-# @todo bug: oracle_vip is not flexible enough.
 # @var oracle_vip:description: >
 # suffix added to hostnames for VIPs.
 #
-# hostnamea{{ oracle_vip }}
+# {{ ansible_hostname  }}{{ oracle_vip }}
+#
+# Important!
+#
+# `oracle_node_vip` defines a fixed hostname for the VIP.
+#
+# That replaces the logic from `oracle_vip` for the VIP!
 # @end
 oracle_vip: -vip
 
@@ -36,16 +41,17 @@ oracle_vip: -vip
 # @end
 oracle_scan_port: 1521
 
-# @todo bug: oracle_ic_net will be removed in the future
 # @var oracle_ic_net:description: >
-# Do not use - is replaced in the future!
-# Reason why RAC support has been disabled...
+# Defines the network for the interconnect.
+#
+# Important!
+#
+# Only used, when `configure_interconnect=true` and `ansible_os_family='RedHat'` during cluster installations.
 # @end
 oracle_ic_net: 3.3.3.{{ ansible_all_ipv4_addresses[0].split(".")[-1] }}
 
 # @var oracle_asm_init_dg:description: >
-# Do not use - is replaced in the future!
-# Reason why RAC support has been disabled...
+# 1st Diskgroup where ASM SPFile is placed.
 # @end
 oracle_asm_init_dg: crs