Docs: Split "Automation rules" into reference and how-to (Diátaxis)

docs/user/automation-rules.rst

@@ -1,19 +1,22 @@
-Automation Rules
+Automation rules
 ================
 
-Automation rules allow project maintainers to automate actions on new branches and tags on repositories.
+Automation rules allow project maintainers to automate actions on new branches and tags on Git repositories.
+If you are familiar with :term:`GitOps`,
+this might seem familiar.
+The goal of Read the Docs' automation rules is to be able to control versioning through your Git repository
+and avoid duplicating these efforts on Read the Docs.
 
-Creating an automation rule
----------------------------
+.. seealso::
 
-#. Go to your project dashboard
-#. Click :guilabel:`Admin` > :guilabel:`Automation Rules`
-#. Click on :guilabel:`Add Rule`
-#. Fill in the fields
-#. Click :guilabel:`Save`
+   :doc:`/guides/automation-rules`
+     A practical guide to managing automated versioning of your documentation.
 
-How do they work?
------------------
+   :doc:`/versions`
+     General explanation of how versioning works for documentation projects on Read the Docs
+
+How automation rules work
+-------------------------
 
 When a new tag or branch is pushed to your repository,
 Read the Docs creates a new version.
@@ -27,27 +30,31 @@ the specified action is performed on that version.
    Versions can match multiple rules,
    and all matching actions will be performed on the version.
 
+Matching a version in Git
+-------------------------
+
 Predefined matches
-------------------
+~~~~~~~~~~~~~~~~~~
 
-Automation rules support several predefined version matches:
+Automation rules support two predefined version matches:
 
 - **Any version**: All new versions will match the rule.
 - **SemVer versions**: All new versions that follow `semantic versioning <https://semver.org/>`__ will match the rule.
 
 User defined matches
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 If none of the above predefined matches meet your use case,
 you can use a **Custom match**.
 
 The custom match should be a valid `Python regular expression <https://docs.python.org/3/library/re.html>`__.
 Each new version will be tested against this regular expression.
 
-Actions
--------
+Actions for versions
+--------------------
 
-When a rule matches a new version, the specified action is performed on that version.
+When a rule matches a new version,
+the specified action is performed on that version.
 Currently, the following actions are available:
 
 - **Activate version**: Activates and builds the version.
@@ -82,11 +89,8 @@ Currently, the following actions are available:
 Order
 -----
 
-The order your rules are listed in  :guilabel:`Admin` > :guilabel:`Automation Rules` matters.
-Each action will be performed in that order,
-so first rules have a higher priority.
-
-You can change the order using the up and down arrow buttons.
+When a new webhook event is received from your Git provider,
+All rules with a successful match will have their action triggered in the order they appear on the :guilabel:`Automation Rules` page.
 
 .. note::
 

docs/user/glossary.rst

@@ -11,6 +11,15 @@ Glossary
       Menu displayed on the documentation, readily accessible for readers, containing the list active versions, links to static downloads, and other useful links.
       Read more in our :doc:`/flyout-menu` page.
 
+   GitOps
+      A popular term,
+      denoting the use of code, branches and tags maintained in Git in order to automate building, testing, and deployment.
+      GitOps is often used for infrastructure such as maintaining the configuration code for infrastructure in Git.
+      In terms of documentation,
+      GitOps is applicable for Read the Docs,
+      as the configuration for building documentation is stored in ``.readthedocs.yaml``,
+      and rules for publication of documentation can be :doc:`fully automated </automation-rules>`.
+
    pre-defined build jobs
       Commands executed by Read the Docs when performing the build process.
       They cannot be overwritten by the user.

docs/user/guides/administrators.rst

@@ -29,3 +29,4 @@ have a look at our :doc:`/tutorial/index`.
    setup-single-sign-on-github-gitlab-bitbucket
    setup-single-sign-on-google-email
    manage-read-the-docs-teams
+   automation-rules

docs/user/guides/automation-rules.rst

@@ -0,0 +1,45 @@
+How to create new versions automatically
+========================================
+
+Versioning documentation to align with the project that it documents does not have to be a manual chore.
+If you are already versioning your Git repository,
+you may define your own rules that can publish your documentation with the same version that you have already specified in Git.
+
+
+How do they work?
+-----------------
+
+When a new tag or branch is pushed to your repository,
+Read the Docs creates a new version.
+
+All rules are evaluated for this version, in the order they are listed.
+If the version matches the version type and the pattern in the rule,
+the specified action is performed on that version.
+
+.. note::
+
+   Versions can match multiple rules,
+   and all matching actions will be performed on the version.
+
+Adding a new rule
+-----------------
+
+#. Go to your project dashboard
+#. Click :guilabel:`Admin` > :guilabel:`Automation Rules`
+#. Click on :guilabel:`Add Rule`
+#. Fill in the fields
+#. Click :guilabel:`Save`
+
+
+Ordering your rules
+-------------------
+
+The order your rules are listed in  :guilabel:`Admin` > :guilabel:`Automation Rules` matters.
+Each action will be performed in that order,
+so first rules have a higher priority.
+
+You can change the order using the up and down arrow buttons.
+
+.. note::
+
+   New rules are added at the end (lower priority).

docs/user/index.rst

@@ -241,7 +241,6 @@ out of your documentation and Read the Docs.
    user-defined-redirects
    automatic-redirects
 
-   automation-rules
    canonical-urls
 
 

docs/user/reference/features.rst

@@ -8,3 +8,4 @@ Features
 
    analytics
    /server-side-search/index
+   /automation-rules