Explore an alternative way of explaining states

docs/user/automation-rules.rst

@@ -73,11 +73,11 @@ Hide version
 
 Make version public
   Sets the version's privacy level to public.
-  See :ref:`versions:Privacy levels`.
+  See :ref:`versions:Version states`.
 
 Make version private
   Sets the version's privacy level to private.
-  See :ref:`versions:Privacy levels`.
+  See :ref:`versions:Version states`.
 
 Set version as default
   Sets the version as the :term:`default version`.

docs/user/commercial/privacy-level.rst

@@ -17,4 +17,4 @@ and changing :guilabel:`Privacy level` to `Public`.
 .. note::
 
    To control access to the documentation itself,
-   see :ref:`versions:privacy levels`.
+   see :ref:`versions:Version states`.

docs/user/commercial/sharing.rst

@@ -35,8 +35,6 @@ Enabling sharing
 
    You can always revoke access in the same panel.
 
-Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
-
 Sharing methods
 ---------------
 

docs/user/commercial/single-sign-on.rst

@@ -13,8 +13,6 @@ Currently, we support two different types of single sign-on:
 * Authentication *and* authorization are managed by the identity provider (GitHub, Bitbucket or GitLab)
 * Authentication (*only*) is managed by the identity provider (Google Workspace account with a verified email address)
 
-Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
-
 .. _sso_git_provider:
 
 Single Sign-on with GitHub, Bitbucket, or GitLab

docs/user/guides/best-practice/links.rst

@@ -62,7 +62,7 @@ Good practice ✅
   Renaming an article's title is great for the reader and great for SEO,
   but this does not have to involve the URL.
 * Establish your understanding of the *latest* and :term:`default version` of your documentation at the beginning. Changing their meaning is very disruptive to incoming links.
-* Keep development versions :ref:`hidden <versions:Hidden>` so people do not find them on search engines by mistake.
+* Keep development versions :ref:`hidden <versions:Version states>` so people do not find them on search engines by mistake.
   This is the best way to ensure that nobody links to URLs that are intended for development purposes.
 * Use a :ref:`version warning <versions:Version warning>` to ensure the reader is aware in case they are reading an old (archived) version.
 

docs/user/guides/pull-requests.rst

@@ -48,7 +48,7 @@ To change the privacy level:
 #. Select your option in :guilabel:`Privacy level of builds from pull requests`
 #. Click on :guilabel:`Save`
 
-Privacy levels work the same way as :ref:`normal versions <versions:privacy levels>`.
+Privacy levels work the same way as :ref:`normal versions <versions:Version states>`.
 
 Limitations
 -----------

docs/user/reference/robots.rst

@@ -11,7 +11,7 @@ It's useful for:
 Read the Docs automatically generates one for you with a configuration that works for most projects.
 By default, the automatically created ``robots.txt``:
 
-* Hides versions which are set to :ref:`versions:Hidden` from being indexed.
+* Hides versions which are set to :ref:`versions:Version states` from being indexed.
 * Allows indexing of all other versions.
 
 .. warning::

docs/user/server-side-search/api.rst

@@ -158,7 +158,7 @@ to include results from subprojects use the ``subprojects`` paramater.
 Authentication and authorization
 --------------------------------
 
-If you are using :ref:`private versions <versions:privacy levels>`,
+If you are using :ref:`private versions <versions:Version states>`,
 users will only be allowed to search projects they have permissions over.
 Authentication and authorization is done using the current session,
 or any of the valid :doc:`sharing methods </commercial/sharing>`.

docs/user/tutorial/index.rst

@@ -415,7 +415,7 @@ and that's why the URLs of your HTML documentation contain the string ``/latest/
 Creating a new version of your documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Read the Docs automatically creates documentation versions from GitHub branches and tags that :ref:`follows some rules <versions:how we envision versions working>` about looking like version numbers, such as ``1.0``, ``2.0.3`` or ``4.x``.
+Read the Docs automatically creates documentation versions from GitHub branches and tags that :ref:`follows some rules <versions:Versioning workflows>` about looking like version numbers, such as ``1.0``, ``2.0.3`` or ``4.x``.
 
 To create version ``1.0`` of your code, and consequently of your documentation:
 
@@ -472,7 +472,7 @@ To activate the ``1.0.x`` version:
 
 .. note::
 
-   Read more about :ref:`hidden versions <versions:hidden>`
+   Read more about :ref:`hidden versions <versions:Version states>`
    in our documentation.
 
 .. "Show a warning for old versions" feature is not available anymore.

docs/user/versions.rst

@@ -14,8 +14,8 @@ create either a tag or branch in your project with that name.
 When you have :doc:`/integrations` configured for your repository,
 we will automatically build each version when you push a commit.
 
-Version states and visibility
------------------------------
+Version states
+--------------
 
 Each version of your documentation has a combination of three states (**Active**, **Public**, and **Hidden**) which determine its visibility on your site:
 
@@ -45,7 +45,7 @@ You can change the states for each version of your documentation in the :guilabe
 **Public** or **Private** (only available on on :doc:`/commercial/index`)
   - Public versions are visible to everyone.
   - Private versions are available only to people who have permissions to see them.
-    They will not display on any list view, and will 404 when you link them to others.
+    They will not display on any list view, and will 404 when visted by people without viewing permissions.
     If you want to share your docs temporarily, see :doc:`/commercial/sharing`.
 
     In addition, if you want other users to view the build page of your public versions,
@@ -93,41 +93,25 @@ they will be redirected to the **Default version**.
 This defaults to **latest**,
 but could also point to your latest released version.
 
-How we envision versions working
---------------------------------
+Versioning workflows
+--------------------
 
-In the normal case,
-the ``latest`` version will always point to the most up to date development code.
-If you develop on a branch that is different than the default for your VCS,
-you should set the **Default Branch** to that branch.
+RTD makes certain assumptions about your documentation version defaults,
+all of which can be reconfigured if you need to:
 
-You should push a **tag** for each version of your project.
-These tags should be numbered in a way that is consistent with semantic versioning.
-This will map to your ``stable`` branch by default.
+- ``latest`` version points to the most up to date development code.
+  If you develop on a branch that is different than the default for your version control system,
+  set the **Default Branch** to the branch you use.
 
-.. note::
-    We in fact are parsing your tag names against the rules given by
-    `PEP 440`_. This spec allows "normal" version numbers like ``1.4.2`` as
-    well as pre-releases. An alpha version or a release candidate are examples
-    of pre-releases and they look like this: ``2.0a1``.
+- **tags** are semantic versioning compatible (according to  `PEP 440`_) snapshots
+  of your documentation. The most recent semantic tag maps to the ``stable`` tag.
 
-    We only consider non pre-releases for the ``stable`` version of your
-    documentation.
+  Semantic versioning allows "normal" version numbers like ``1.4.2``, as
+  well as pre-releases like this: ``2.0a1``. The ``stable`` version of your documentation never includes a pre-release.
 
-If you have documentation changes on a **long-lived branch**,
-you can build those too.
-This will allow you to see how the new docs will be built in this branch of the code.
-Generally you won't have more than 1 active branch over a long period of time.
-The main exception here would be **release branches**,
-which are branches that are maintained over time for a specific release number.
+- If you have documentation changes on a **long-lived branch**,
+  you can build those too, to see how the new docs will be built.
+  Generally you won't have more than 1 active branch over a long period of time,
+  apart from **release branches**, maintained over time for a specific release.
 
 .. _PEP 440: https://www.python.org/dev/peps/pep-0440/
-
-Logging out
------------
-
-When you log in to a documentation site, you will be logged in until you close your browser.
-To log out, click on the :guilabel:`Log out` link in your documentation's :term:`flyout menu`.
-This is usually located in the bottom right or bottom left, depending on the theme design.
-This will log you out from the current domain,
-but not end any other session that you have active.