Documentation updates

README.adoc

@@ -4,33 +4,29 @@ toc::[]
 :sectnums:
 :sectnumlevels: 4
 
+== `ansible-oracle`
+* Automated installation of
+   ** Oracle RAC databases
+   ** RAC One Node database and
+   ** single instance Oracle databases
+* Start with one or more clean Linux machine(s), end up with a fully configured Oracle database system
 
-== Feauturelist and Supported options in `ansible-oracle`
+== Documentation
 
-* Installs Oracle RAC, RAC One Node and normal single instances.
-* Start with one or more clean machine(s), end up with a fully
-configured RAC Cluster.
+Read link:doc/featurelist.adoc[here] for a detailed list of features of `ansible-oracle`.
 
-Read link:doc/feauturelist.adoc[here] for a full list of all feautures of `ansible-oracle`.
+=== Getting started
+* link:doc/vagrant.adoc[Vagrant Setup on Windows]: Preparation for beginner
+* link:doc/guides/beginner.adoc[Beginner]: Guiding you through your first setup
 
-== Getting started
-
-The documentation has been split in different parts:
-
-* link:doc/vagrant.adoc[Vagrant Setup on Windows]:
-
-=== Usage examples
-
-* Usage examples:
-** link:doc/guides/beginner.adoc[Beginner] +
-Start link:doc/guides/beginner.adoc[here] for 1st test of ansible-oracle.
-////
-** advanced Users
-** Experts +
-Start here, when the setup for advanced Users works fine for you.
-
-* TODO: Running link:doc/ansible.adoc[Ansible in Docker-Container]
-////
+=== Next steps
 * How to link:doc/development.adoc[develop in ansible-oracle]
-
 * List of link:doc/roles.adoc[roles in ansible-oracle]
+* Running link:doc/ansible.adoc[Ansible in Docker-Container]
+* Running link:doc/[Read the full documentation]
+
+
+## Pre-requisites
+* Ansible Version >= 2.9.   (Version 2.12 or newer of Ansible is recommended)
+* Oracle Linux (or any RHEL-based Linux System) >= 7
+* Oracle Database/Grid Infrastructure 21.3.0.0, 19.3.0.0

README.md

@@ -1,19 +1,38 @@
 # ansible-oracle
 
+
 _IMPORTANT_
 
 *This an a beta release of `ansible-oracle`.* Use Version 3.x for production instead of this version.
 
-Read documentation at <https://github.com/oravirt/ansible-oracle> for more details.
 
-* Installs Oracle RAC, RAC One Node and normal single instances.
-* Start with one or more clean machine(s), end up with a fully
-configured RAC Cluster.
+* Automated installation of
+   * Oracle RAC databases
+   * RAC One Node database and
+   * single instance Oracle databases
+* Start with one or more clean Linux machine(s), end up with a fully configured Oracle database system
+
+# Documentation
+
+## Features
+1. Full list of features of ansible-oracle <https://github.com/oravirt/ansible-oracle/blob/master/doc/featurelist.adoc>
+1. More details <https://github.com/oravirt/ansible-oracle>
+
+
+## Getting Started
+1. Vagrant setup on Windows <https://github.com/oravirt/ansible-oracle/blob/master/doc/vagrant.adoc>
+1. Beginner <https://github.com/oravirt/ansible-oracle/blob/master/doc/guides/beginner.adoc>
+
+### Next Steps
+1. Read the full documentation <https://github.com/oravirt/ansible-oracle/tree/master/doc>
+1. How to develop in ansible-oracle <https://github.com/oravirt/ansible-oracle/blob/master/doc/development.adoc>
+1. List of roles in ansible-oracle <https://github.com/oravirt/ansible-oracle/blob/master/doc/roles.adoc>
+
 
 ## Pre-requisites
 
-* Ansible >= 2.14
+* Ansible Version >= 2.14
 
-  2.12 is recommended
+  Version 2.14 or newer of Ansible is recommended
 * Oracle Linux (or any RHEL-based Linux System) >= 7
 * Oracle Database/Grid Infrastructure 21.3.0.0, 19.3.0.0

changelogs/fragments/docs.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - "Documentation updates (oravirt#389)"

README-ansible.adoc → doc/README-ansible.adoc

@@ -2,12 +2,12 @@
 :toc-placement!:
 toc::[]
 
-IMPORTANT: This documentation is work in progress!
+IMPORTANT: This documentation is a work in progress!
 
-= Ansible as Docker Container
+= Ansible as a Docker Container
 
 The development and test of `ansible-oracle` is done in a Docker Container.
-This allows a simple switch between versions and an easy implementation at a customer side, because you can use a reserved version of Ansible for `ansible-oracle`.
+This allows a simple switch between ansible versions and an easy implementation at a customer site, because you can use your own chosen version of Ansible for `ansible-oracle`.
 
 Requirements:
 

doc/chocolatey.puml

@@ -6,7 +6,7 @@ System_Boundary(host, "Host System", "PC/Notebook") {
   System_Boundary(tools, "Tools") {
     Component(gitbash, "git+bash", "git+bash for Windows")
     Component(vagrant, "Vagrant", "Hashicorp Vagrant")
-    Component(virtualbox, "VirtualBox", "VirtualBox")
+    Component(virtualbox, "VirtualBox", "Oracle VirtualBox")
     Component_Ext(vscode, "VSCode", "Visual Studio Code")
     Component_Ext(conemu, "ConEmu", "ConEmu")
   }

doc/development.adoc

@@ -1,6 +1,8 @@
 :toc:
 :toc-placement!:
+:toclevels: 4
 toc::[]
+
 :sectnums:
 :sectnumlevels: 4
 
@@ -18,7 +20,7 @@ You need an Ansible-Controller with an Editor or IDE of your own choice.
 
 === Create Fork on github and contribute to the project
 
-link:https://docs.github.com/en/get-started/quickstart/contributing-to-projects[github] has a great documentation with details about creating a fork and branch to contribute to `ansible-oracle`.
+link:https://docs.github.com/en/get-started/quickstart/contributing-to-projects[github] has some great documentation with details about creating a fork and branch to contribute to `ansible-oracle`.
 
 IMPORTANT: The `github-Actions` will automatically start, when the branchname starts with `pr` or in each Pull-Request. +
 Please use a branch with 'pr'--prefix, when `ansible-lint` should be checked for each commit.
@@ -42,7 +44,7 @@ pre-commit run
 
 === Ansible Navigator
 
-IMPORTANT: python3 should point to Python >=3.9, otherwise ansible-navigator and ansible-lint could not beused. +
+IMPORTANT: python3 should point to Python >=3.9, otherwise `ansible-navigator` and `ansible-lint` could not be used. +
 The `activate` script is used to change the Python environment in current shell.
 
 .configure venv for ansible-oracle
@@ -70,7 +72,7 @@ ansible-navigator 3.3.0
 
 === Using ansible-doctor
 
-IMPORTANT: `ansible-doctor` has har dmodule dpendencies with conflicts between `ansible-lint`.
+IMPORTANT: `ansible-doctor` has module dpendencies with conflicts between `ansible-lint`.
 We have to use a dedicated venv for `ansible-doctor'
 
 .configure venv for ansible-oracle
@@ -109,8 +111,6 @@ cd ansible-oracle
 
 === Start Ansible-Container
 
-IMPORTANT: Replaced by `ansible-navigator` and `venv`.
-
 === Start Playbook
 
 IMPORTANT: Don't forget to set the working branch in `requirements.yml`. +
@@ -137,7 +137,7 @@ ansible-galaxy collection install --force -r requirements.yml && ansible-playboo
 
 === Important Information
 
-The ansible-oracle project introduced `antsibull-changelog` for managing the `CHANGELOG.rst` based on fragments in `changelogs/gragments`.
+The ansible-oracle project introduced `antsibull-changelog` for managing the `CHANGELOG.rst` based on fragments in `changelogs/fragments`.
 
 The ID should point to the PR and the filename describe the PR in short form.
 The fragments are part of the PR.
@@ -168,7 +168,7 @@ Changelogs for Collections: https://github.com/ansible-community/antsibull-chang
 `antsibull-changelog release` reads `galaxy.yml` to get the release version automatically.
 The execution is aborted, when a release with the version is existing in `CHANGELOG.rst`.
 
-NOTE: The whole release process should be donw with a dedicated Pull-Request.
+NOTE: The whole release process should be done with a dedicated Pull-Request.
 
 ----
 antsibull-changelog release

doc/feauturelist.adoc → doc/featurelist.adoc

@@ -1,11 +1,11 @@
 
-## Supported feautures in ansible-oracle
+## Supported features in ansible-oracle
 
 WARNING: Please check the official Compatibilty List from Oracle for RDBMS and Restart/Grid-Infrastructure. +
 `ansible-oracle` only supports combinations from Oracle with exceptions from the following table.
 
 IMPORTANT: All Editions from Oracle are supported.
-See documentation from Oracle for differences between Enterprise and Stadard Edtion (SE, SE One and SE2)
+See documentation from Oracle for differences between Enterprise and Standard Edtion (SE, SE One and SE2)
 
 
 :supportedfrom112: 11.2.0.3 <<table1footnote,[1]>> \
@@ -25,7 +25,7 @@ See documentation from Oracle for differences between Enterprise and Stadard Edt
 :supportedfrom19: 19c + \
 21c
 
-.Feauturelist
+.Featurelist
 [options="header" cols="1,2,2" valign="top"]
 |=======================
 |Group |Option |Version
@@ -35,6 +35,7 @@ Redhat Enterprise Linux
 |6 <<table1footnote,^[1]^>> +
 7 +
 8 +
+9 (experimental!) <<table1footnote,^[5]^>>
 
 |SuSE Linux Enterprise Server<<table1footnote,^[3]^>>
 |15, 15.3
@@ -50,9 +51,8 @@ Redhat Enterprise Linux
 
 .5+|Software
 |Ansible
-|2.9 <<table1footnote,^[9]^>> +
-2.10 +
-2.12 (used for all tests)
+|2.14 or newer <<table1footnote,^[9]^>> +
+
 |Oracle RDBMS
 |{supportedfrom112}
 
@@ -63,12 +63,11 @@ Redhat Enterprise Linux
 |{supportedfrom12}
 
 |cxOracle for Python
-|Python 2, 3
+|Python 3
 
 .3+|ASM
 |ASM Filter Driver (ASMFD)
-|19c (experimental! <<table1footnote,^[2]^>>) +
-21c (experimental! <<table1footnote,^[2]^>>)
+|{supportedfrom19}
 
 |ASMlib
 |{supportedfrom12}
@@ -128,15 +127,16 @@ e|Database Services <<table1footnote,^[3]^>>
 |Timezone Upgrades
 |{supportedfrom12}
 
-.3+|Database Patching
+.4+|Database Patching
 |Release Updates<<table1footnote,^[11]^>>
-.3+|{supportedfrom12}
+.4+|{supportedfrom12}
 
 a|OneOff Patches<<table1footnote,^[11]^>>
 
 - Install
 - Remove with unique patch id option
 |automatic datapatch execution<<table1footnote,^[11]^>>
+|Patch Download from Oracle
 
 |Environment script
 a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scripts[`ocenv`] for Oracle
@@ -150,13 +150,10 @@ a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scrip
   Was supported by `ansible-oracle`. It is not tested anymore.
 [[table1footnote]]^2^::
   Still in development and not fully tested at the moment.
-  Breaking changes in new commits are possivle. +
-  Please do not use it in production environments.
+  Breaking changes in new commits are possible. +
+  Please do not use this feature in production environments.
 [[table1footnote]]^3^::
   Limited support. Not tested for Oracle Restart & Grid-Infrastructure
-[[table1footnote]]^4^::
-  2.9 is minimum version with limited support for Ansible Collections. +
-  Please use 2.10 as a minimum.
 [[table1footnote]]^5^::
   in development and not implemented at the moment.
 [[table1footnote]]^6^::
@@ -166,10 +163,8 @@ a|dynamic shell environment link:https://github.com/opitzconsulting/oracle-scrip
 [[table1footnote]]^8^::
   only create/drop PDB
 [[table1footnote]]^9^::
-  `ansible-oracle` is based on a Collection. +
-  Ansible 2.9 has limited support for Collections.
-  You should use 2.10 or newer.
+  Ansible 2.14 or newer is mandatory since `ansible-oracle` Version 4.2.
 [[table1footnote]]^10^::
-  Use the Golden-Image feauture as a work arround.
+  Use the Golden-Image feature as a workaround.
 [[table1footnote]]^11^::
   Supported for Single-Instance, Oracle Restart and Oracle Grid-Infrastructure.