Port FAQ docs from 0.x and update for 1.0

- Moved workflow diagram to FAQs
- Added live demos
- Removed web screenshots
- Combined "Why is ARA being developed" with
  "Why don't you use Ansible Tower (AWX), Rundeck or Semaphore"

Change-Id: Id7da538b8bce52f85ef4c4422a48d3b8b7588150

doc/source/ara-plugin-configuration.rst

@@ -20,6 +20,8 @@ under the ara namespace, like so:
     [ara]
     variable = value
 
+.. _configuration_callback:
+
 ARA callback plugin
 -------------------
 

doc/source/ara-record.rst

@@ -1,3 +1,5 @@
+.. _ara_record:
+
 Recording arbitrary data in playbooks
 =====================================
 

doc/source/architecture.rst

@@ -1,20 +0,0 @@
-Architecture and Workflows
-==========================
-
-Recording data from Ansible
----------------------------
-
-ARA Records Ansible playbooks through an Ansible `callback plugin`_.
-
-.. image:: _static/graphs/recording-workflow.png
-
-0. ARA is installed and Ansible is configured to use the callback plugin
-1. An ``ansible-playbook`` command is executed
-2. Ansible triggers the callback plugin for every event (``v2_playbook_on_start``, ``v2_runner_on_failed``, etc.)
-3. The relevant information is retrieved from the Ansible playbook execution context and is sent to the API server
-4. The API server validates and serializes the data before storing it the configured database backend
-5. The API server sends a response back to the API client with the results
-6. The callback plugin returns, ending the callback hook
-7. Ansible continues running the playbook until it fails or is completed (back to step 2)
-
-.. _callback plugin: https://docs.ansible.com/ansible/latest/plugins/callback.html

doc/source/faq.rst

@@ -0,0 +1,127 @@
+FAQ
+===
+
+What is ARA ?
+-------------
+
+ARA Records `Ansible <https://wwwansible.com>`_ playbooks and makes them easier to understand and troubleshoot.
+
+ARA is currently composed of three different free and open source projects:
+
+- https://github.com/ansible-community/ara for the REST API server and Ansible plugins
+- https://github.com/ansible-community/ara-web for the standalone web interface
+- https://github.com/ansible-community/ara-infra for project-specific infrastructure needs (such as the `ara.recordsansible.org <https://ara.recordsansible.org>`_ website)
+
+How does it work ?
+------------------
+
+ARA Records Ansible playbooks through an Ansible `callback plugin`_.
+
+.. image:: _static/graphs/recording-workflow.png
+
+0. ARA is installed and Ansible is configured to use the callback plugin
+1. An ``ansible-playbook`` command is executed
+2. Ansible triggers the callback plugin for every event (``v2_playbook_on_start``, ``v2_runner_on_failed``, etc.)
+3. The relevant information is retrieved from the Ansible playbook execution context and is sent to the API server
+4. The API server validates and serializes the data before storing it the configured database backend
+5. The API server sends a response back to the API client with the results
+6. The callback plugin returns, ending the callback hook
+7. Ansible continues running the playbook until it fails or is completed (back to step 2)
+
+Once the data has been saved in the database, it is made available for query by
+the API.
+
+.. _callback plugin: https://docs.ansible.com/ansible/latest/plugins/callback.html
+
+What's an Ansible callback ?
+----------------------------
+
+`Ansible Callbacks`_ are essentially hooks provided by Ansible. Ansible will
+send an event and you can react to it with a callback.
+You could use a callback to do things like print additional details or, in the
+case of ARA, record the playbook run data in a database.
+
+.. _Ansible Callbacks: https://docs.ansible.com/ansible/dev_guide/developing_plugins.html
+
+Are there live demos available ?
+--------------------------------
+
+Yes, you can find persistent and up-to-date live demos at
+`api.demo.recordsansible.org <https://api.demo.recordsansible.org>`_ for the
+API and `web.demo.recordsansible.org <https://web.demo.recordsansible.org>`_ for
+the ara-web_ standalone interface.
+
+What versions of Ansible are supported ?
+----------------------------------------
+
+The upstream Ansible community and maintainers provide support for the latest
+three major stable releases and ARA follows the same support cycle.
+
+For example, if the latest version of Ansible is 2.8, then the latest release
+of ARA will support 2.8 as well as 2.7 and 2.6.
+
+For more information on Ansible's release and maintenance cycle, you can refer
+to the `Ansible documentation <https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html>`_.
+
+If you are using a release of Ansible that is no longer supported, we strongly
+encourage you to upgrade as soon as possible in order to benefit from the
+latest features and security fixes.
+
+Older unsupported versions of Ansible can contain unfixed security
+vulnerabilities (*CVE*).
+
+What versions of Python are supported ?
+---------------------------------------
+
+Before version 1.0 of ARA, both python2 and python3 were supported.
+Versions of ARA after 1.0 are not designed to support python2 in consideration
+that python2 will reach end of life in `January 2020 <https://pythonclock.org/>`_.
+
+Why ARA instead of <X> ?
+------------------------
+
+Ansible is an awesome tool. It can be used for a lot of things.
+
+Reading and interpreting the output of an ``ansible-playbook`` run, especially
+one that is either long running, involves a lot of hosts or prints a lot of
+output can be hard to understand and troubleshoot.
+
+This is especially true when you happen to be running Ansible hundreds of times
+during the day, through automated means -- for example when doing continuous
+integration or continuous delivery.
+
+ARA aims to do one thing and do it well: Record Ansible playbooks and provide
+you with the tools you need to make your playbook results intuitive for you and
+for your systems.
+
+The great thing about ARA is that it is not mutually exclusive with other
+software and systems you might already be using Ansible with today.
+
+There is nothing preventing you from using ARA with other tools such as `Ansible
+Tower`_ (or AWX_), Zuul_, Jenkins_ or Rundeck_ since all you need to get started is
+to install and enable the ARA Ansible callback plugin.
+
+.. _Ansible Tower: https://www.ansible.com/tower
+.. _AWX: https://github.com/ansible/awx
+.. _Zuul: https://zuul-ci.org
+.. _Jenkins: https://www.redhat.com/en/blog/integrating-ansible-jenkins-cicd-process
+.. _Rundeck: https://www.rundeck.com/ansible
+
+Can I set up the different components of ARA on different servers ?
+-------------------------------------------------------------------
+
+Yes.
+
+The defaults are set to have the callback use the offline API client which
+expects the server dependencies installed and the data is saved to a local
+sqlite database.
+
+However, the callback can also be configured to send data to a specified API
+server address and the API server can be configured to use a remote database
+server such as PostgreSQL or MySQL.
+
+The web client interface provided by ara-web_ is stateless and requires an API
+server address to connect to.
+It can be installed anywhere that has access to the API server.
+
+.. _ara-web: https://github.com/ansible-community/ara-web

doc/source/index.rst

@@ -8,6 +8,7 @@ Table of Contents
 .. toctree::
     :maxdepth: 2
 
+    Frequently asked questions <faq>
     Installing ARA <installation>
     Configuring Ansible to use ARA <ansible-configuration>
     Configuring the ARA Ansible plugins <ara-plugin-configuration>
@@ -17,7 +18,6 @@ Table of Contents
     API: Usage with built-in clients <api-usage>
     Setting playbook names and labels <playbook-names-and-labels>
     Recording arbitrary data in playbooks <ara-record>
-    Architecture and workflows <architecture>
     Contributing to ARA <contributing>
 
 .. toctree::