Contributor guide and adjusted titles (#14447)

Co-authored-by: Thanhnguyet Vo <tvo@ansible.com>

12 files changed, 267 insertions, 29 deletions

diff --git a/docs/docsite/rst/administration/index.rst b/docs/docsite/rst/administration/index.rst
index cada431cd3..4ad7cf36eb 100644
--- a/docs/docsite/rst/administration/index.rst
+++ b/docs/docsite/rst/administration/index.rst
@@ -1,10 +1,22 @@
 .. _ag_start:
 
-==================
-AWX Administration
-==================
+=============================
+Administering AWX Deployments
+=============================
+
+Learn how to administer AWX deployments through custom scripts, management jobs, and DevOps workflows.
+This guide assumes at least basic understanding of the systems that you manage and maintain with AWX.
+
+This guide applies to the latest version of AWX only.
+The content in this guide is updated frequently and might contain functionality that is not available in previous versions.
+Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version.
+
+**Join us online**
+
+We talk about AWX documentation on Matrix at `#docs:ansible.im <https://matrix.to/#/#docs:ansible.im>`_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs!
+
+You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com <https://forum.ansible.com/>`_.
 
-AWX Administration
 
 .. toctree::
   :maxdepth: 2
diff --git a/docs/docsite/rst/contributor/index.rst b/docs/docsite/rst/contributor/index.rst
new file mode 100644
index 0000000000..5b4f1e172b
--- /dev/null
+++ b/docs/docsite/rst/contributor/index.rst
@@ -0,0 +1,23 @@
+.. _contributor_guide:
+
+=======================
+AWX Contributor's Guide
+=======================
+
+Want to get involved with the AWX community?
+Great!
+There are so many ways you can contribute to AWX.
+
+**Join us online**
+
+You can chat with us and ask questions on Matrix at `#awx:ansible.com <https://matrix.to/#/#awx:ansible.com>`_.
+Also visit the `forum.ansible.com <https://forum.ansible.com/>`_ to find contributor resources.
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   intro
+   setting_up
+   work_items
+   report_issues
\ No newline at end of file
diff --git a/docs/docsite/rst/contributor/intro.rst b/docs/docsite/rst/contributor/intro.rst
new file mode 100644
index 0000000000..2bbdecc523
--- /dev/null
+++ b/docs/docsite/rst/contributor/intro.rst
@@ -0,0 +1,7 @@
+
+Introduction
+=============
+
+Hi there! We're excited to have you as a contributor.
+
+Have questions about this document or anything not covered here? Come chat with us at `#ansible-awx` on irc.libera.chat, or submit your question to the `mailing list <https://groups.google.com/forum/#!forum/awx-project>`_.
diff --git a/docs/docsite/rst/contributor/report_issues.rst b/docs/docsite/rst/contributor/report_issues.rst
new file mode 100644
index 0000000000..c16f3fb1d5
--- /dev/null
+++ b/docs/docsite/rst/contributor/report_issues.rst
@@ -0,0 +1,22 @@
+
+.. _docs_report_issues:
+
+Reporting Issues
+================
+
+To report issues you find in the AWX documentation, use the GitHub [issue tracker](https://github.com/ansible/awx/issues) for filing bugs. In order to save time, and help us respond to issues quickly, make sure to fill out as much of the issue template
+as possible. Version information, and an accurate reproducing scenario are critical to helping us identify the problem.
+
+Be sure to attach the ``component:docs`` label to your issue. These labels are determined by the template data. Please use the template and fill it out as accurately as possible.
+
+Please don't use the issue tracker as a way to ask how to do something. Instead, use the `mailing list <https://groups.google.com/forum/#!forum/awx-project>`_, and the ``#ansible-awx`` channel on irc.libera.chat to get help.
+
+Before opening a new issue, please use the issue search feature to see if what you're experiencing has already been reported. If you have any extra detail to provide, please comment. Otherwise, rather than posting a "me too" comment, please consider giving it a `"thumbs up" <https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comment>`_ to give us an indication of the severity of the problem.
+
+See `How issues are resolved <https://github.com/ansible/awx/blob/devel/ISSUES.md#how-issues-are-resolved>`_ for more information about the triaging and resolution process.
+
+
+Getting help
+-------------
+
+If you require additional assistance, please reach out to us at ``#ansible-awx`` on irc.libera.chat, or submit your question or concern on the `mailing list <https://groups.google.com/forum/#!forum/awx-project>`_, or `Discourse <https://forum.ansible.com/tag/documentation>`_.
diff --git a/docs/docsite/rst/contributor/setting_up.rst b/docs/docsite/rst/contributor/setting_up.rst
new file mode 100644
index 0000000000..95730e61b1
--- /dev/null
+++ b/docs/docsite/rst/contributor/setting_up.rst
@@ -0,0 +1,76 @@
+
+Setting up your development environment
+========================================
+
+The AWX docs are developed using the Python toolchain. The content itself is authored in ReStructuredText (rst).
+
+Prerequisites
+---------------
+
+.. contents::
+    :local:
+
+
+Fork and clone the AWX repo
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have not done so already, you'll need to fork the AWX repo on GitHub. For more on how to do this, see `Fork a Repo <https://help.github.com/articles/fork-a-repo/>`_.
+
+
+Install python and setuptools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install the setuptools package on Linux using pip:
+
+
+1. If not already installed, `download the latest version of Python3 <https://www.geeksforgeeks.org/how-to-download-and-install-python-latest-version-on-linux/>`_ on your machine.
+
+2. Check if pip3 and python3 are correctly installed in your system using the following command:
+
+::
+
+	python3 --version
+	pip3 --version
+
+3. Upgrade pip3 to the latest version to prevent installation issues:
+
+::
+
+	pip3 install --upgrade pip
+
+4. Install Setuptools:
+
+::
+
+	pip3 install setuptools
+
+5. Verify whether the Setuptools has been properly installed: 
+
+::
+
+	import setuptools
+
+If no errors are returned, then the package was installed properly.
+
+6. Install the tox package so you can build the docs locally:
+
+::
+
+	pip3 install tox
+
+
+
+Run local build of the docs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To build the docs on your local machine, use the tox utility. In your forked branch of your AWX repo, run: 
+
+::
+
+	tox -e docs  
+
+
+Access the AWX user interface
+------------------------------
+
+To access an instance of the AWX interface, refer to `Build and run the development environment <https://github.com/ansible/awx/blob/devel/CONTRIBUTING.md#setting-up-your-development-environment>`_ for detail. Once you have your environment setup, you can access the AWX UI by logging into it at `https://localhost:8043 <https://localhost:8043>`_, and access the API directly at `https://localhost:8043/api/ <https://localhost:8043/api/>`_.
diff --git a/docs/docsite/rst/contributor/work_items.rst b/docs/docsite/rst/contributor/work_items.rst
new file mode 100644
index 0000000000..54c1256e4c
--- /dev/null
+++ b/docs/docsite/rst/contributor/work_items.rst
@@ -0,0 +1,46 @@
+
+What should I work on?
+=======================
+
+Good first issue
+-----------------
+
+We have a `"good first issue" label` <https://github.com/ansible/awx/issues?q=is%3Aopen+label%3A%22good+first+issue%22+label%3Acomponent%3Adocs+) we put on some doc issues that might be a good starting point for new contributors with the following filter:
+
+::
+
+	is:open label:"good first issue" label:component:docs 
+
+
+Fixing and updating the documentation are always appreciated, so reviewing the backlog of issues is always a good place to start.
+
+
+Things to know prior to submitting revisions
+----------------------------------------------
+
+- All doc revisions or additions are done through pull requests against the ``devel`` branch.
+- You must use ``git commit --signoff`` for any commit to be merged, and agree that usage of ``--signoff`` constitutes agreement with the terms of `DCO 1.1 <https://github.com/ansible/awx/blob/devel/DCO_1_1.md>`_.
+- Take care to make sure no merge commits are in the submission, and use ``git rebase`` vs ``git merge`` for this reason.
+  - If collaborating with someone else on the same branch, consider using ``--force-with-lease`` instead of ``--force``. This will prevent you from accidentally overwriting commits pushed by someone else. For more information, see `git push docs <https://git-scm.com/docs/git-push#git-push---force-with-leaseltrefnamegt>`_.
+- If submitting a large doc change, it's a good idea to join the ``#ansible-docs`` channel on irc.libera.chat or `Discourse <https://forum.ansible.com/tag/documentation>`_, and talk about what you would like to do or add first. This not only helps everyone know what's going on, it also helps save time and effort, if the community decides some changes are needed.
+- We ask all of our community members and contributors to adhere to the `Ansible code of conduct <http://docs.ansible.com/ansible/latest/community/code_of_conduct.html>`_. If you have questions, or need assistance, please reach out to our community team at `codeofconduct@ansible.com <mailto:codeofconduct@ansible.com>`_.
+
+
+**NOTES**
+
+> Issue assignment will only be done for maintainers of the project. If you decide to work on an issue, please feel free to add a comment in the issue to let others know that you are working on it; but know that we will accept the first pull request from whomever is able to fix an issue. Once your PR is accepted we can add you as an assignee to an issue upon request. 
+
+
+> If you work in a part of the docs that is going through active development, your changes may be rejected, or you may be asked to `rebase`. A good idea before starting work is to have a discussion with us in the ``#ansible-awx`` channel on irc.libera.chat, or on the `mailing list <https://groups.google.com/forum/#!forum/awx-project>`_, or `Discourse <https://forum.ansible.com/tag/documentation>`_.
+
+> If you find an issue with the functions of the UI or API, please see the `Reporting Issues <https://github.com/ansible/awx/blob/devel/CONTRIBUTING.md#reporting-issues>`_ section to open an issue. 
+
+> If you find an issue with the docs themselves, refer to :ref:`docs_report_issues`.
+
+
+Translations
+-------------
+
+At this time we do not accept PRs for adding additional language translations as we have an automated process for generating our translations. This is because translations require constant care as new strings are added and changed in the code base. Because of this the .po files are overwritten during every translation release cycle. We also can't support a lot of translations on AWX as its an open source project and each language adds time and cost to maintain. If you would like to see AWX translated into a new language please create an issue and ask others you know to upvote the issue. Our translation team will review the needs of the community and see what they can do around supporting additional language.
+
+If you find an issue with an existing translation, please see the `Reporting Issues <https://github.com/ansible/awx/blob/devel/CONTRIBUTING.md#reporting-issues>`_ section to open an issue and our translation team will work with you on a resolution. 
diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst
index 318cfcab97..1388862c8e 100644
--- a/docs/docsite/rst/index.rst
+++ b/docs/docsite/rst/index.rst
@@ -5,36 +5,37 @@ Ansible AWX helps teams manage complex multi-tier deployments by adding control,
 
 .. toctree::
    :maxdepth: 2
-   :caption: AWX Quickstart
+   :caption: Get started
 
    quickstart/index
 
 .. toctree::
    :maxdepth: 2
-   :caption: User Guide
+   :caption: Community
 
-   userguide/index
+   contributor/index
 
 .. toctree::
    :maxdepth: 2
-   :caption: AWX Administration
+   :caption: Users
 
-   administration/index
+   userguide/index
 
 .. toctree::
    :maxdepth: 2
-   :caption: AWX REST API
+   :caption: Developers
 
    rest_api/index
 
 .. toctree::
    :maxdepth: 2
-   :caption: Upgrades and Migrations
+   :caption: Administrators
 
+   administration/index
    upgrade_migration/index
 
 .. toctree::
    :maxdepth: 2
-   :caption: Release Notes
+   :caption: Release notes
 
    release_notes/index
diff --git a/docs/docsite/rst/quickstart/index.rst b/docs/docsite/rst/quickstart/index.rst
index ecfa844e93..e946a010e9 100644
--- a/docs/docsite/rst/quickstart/index.rst
+++ b/docs/docsite/rst/quickstart/index.rst
@@ -4,7 +4,17 @@
 AWX Quickstart
 ==============
 
-AWX Quickstart
+Complete the basic steps for using AWX and running your first playbook.
+
+This guide applies to the latest version of AWX only.
+The content in this guide is updated frequently and might contain functionality that is not available in previous versions.
+Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version.
+
+**Join us online**
+
+We talk about AWX documentation on Matrix at `#docs:ansible.im <https://matrix.to/#/#docs:ansible.im>`_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs!
+
+You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com <https://forum.ansible.com/>`_.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/docsite/rst/release_notes/index.rst b/docs/docsite/rst/release_notes/index.rst
index 3122bc6092..710d881bb4 100644
--- a/docs/docsite/rst/release_notes/index.rst
+++ b/docs/docsite/rst/release_notes/index.rst
@@ -1,10 +1,20 @@
 .. _releasenotes_start:
 
-=================
-AWX Release Notes
-=================
+=============
+Release Notes
+=============
 
-AWX Release Notes
+AWX release notes, known issues, and related reference materials.
+
+This guide applies to the latest version of AWX only.
+The content in this guide is updated frequently and might contain functionality that is not available in previous versions.
+Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version.
+
+**Join us online**
+
+We talk about AWX documentation on Matrix at `#docs:ansible.im <https://matrix.to/#/#docs:ansible.im>`_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs!
+
+You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com <https://forum.ansible.com/>`_.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/docsite/rst/rest_api/index.rst b/docs/docsite/rst/rest_api/index.rst
index 2ac5222078..5a3031a275 100644
--- a/docs/docsite/rst/rest_api/index.rst
+++ b/docs/docsite/rst/rest_api/index.rst
@@ -1,10 +1,20 @@
 .. _api_start:
 
-============
-AWX REST API
-============
+=================
+AWX API Reference
+=================
 
-AWX REST API
+Developer reference for the AWX API.
+
+This guide applies to the latest version of AWX only.
+The content in this guide is updated frequently and might contain functionality that is not available in previous versions.
+Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version.
+
+**Join us online**
+
+We talk about AWX documentation on Matrix at `#docs:ansible.im <https://matrix.to/#/#docs:ansible.im>`_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs!
+
+You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com <https://forum.ansible.com/>`_.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/docsite/rst/upgrade_migration/index.rst b/docs/docsite/rst/upgrade_migration/index.rst
index 9ec181bde2..0845ae467f 100644
--- a/docs/docsite/rst/upgrade_migration/index.rst
+++ b/docs/docsite/rst/upgrade_migration/index.rst
@@ -1,10 +1,20 @@
 .. _upgrade_migration_start:
 
-=======================================
-Upgrading and Migrating AWX Deployments
-=======================================
+=======================
+Upgrades and Migrations
+=======================
 
-Upgrading and Migrating AWX Deployments
+Review important information before upgrading or migrating AWX deployments.
+
+This guide applies to the latest version of AWX only.
+The content in this guide is updated frequently and might contain functionality that is not available in previous versions.
+Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version.
+
+**Join us online**
+
+We talk about AWX documentation on Matrix at `#docs:ansible.im <https://matrix.to/#/#docs:ansible.im>`_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs!
+
+You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com <https://forum.ansible.com/>`_.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/docsite/rst/userguide/index.rst b/docs/docsite/rst/userguide/index.rst
index 22417b6748..11d0ca0986 100644
--- a/docs/docsite/rst/userguide/index.rst
+++ b/docs/docsite/rst/userguide/index.rst
@@ -1,10 +1,21 @@
 .. _ug_start:
 
-==========
-User Guide
-==========
+===================
+Automating with AWX
+===================
 
-User Guide
+Learn how to use AWX functionality to scale and manage your automation.
+This guide assumes moderate familiarity with Ansible, including concepts such as **Playbooks**, **Variables**, and **Tags**.
+
+This guide applies to the latest version of AWX only.
+The content in this guide is updated frequently and might contain functionality that is not available in previous versions.
+Likewise content in this guide can be removed or replaced if it applies to functionality that is no longer available in the latest version.
+
+**Join us online**
+
+We talk about AWX documentation on Matrix at `#docs:ansible.im <https://matrix.to/#/#docs:ansible.im>`_ and on libera IRC at ``#ansible-docs`` if you ever want to join us and chat about the docs!
+
+You can also find lots of AWX discussion and get answers to questions at `forum.ansible.com <https://forum.ansible.com/>`_.
 
 .. toctree::
    :maxdepth: 2