docs: update documentation around version warning banner (#10877)

* update documentation around version warning banner * match indentation from previous author * trim trailing whitespace * Update docs/user/versions.rst Co-authored-by: Manuel Kaufmann <[email protected]> * Update docs/user/versions.rst Co-authored-by: Manuel Kaufmann <[email protected]> * remove obsolete note --------- Co-authored-by: Manuel Kaufmann <[email protected]>
readthedocs · Nov 8, 2023 · 0691bcb · 0691bcb
1 parent 6410aa0
commit 0691bcb
Showing 1 changed file with 13 additions and 20 deletions.
diff --git a/docs/user/versions.rst b/docs/user/versions.rst
@@ -149,31 +149,24 @@ Version Control Support Matrix
 Version warning
 ---------------
 
-This is a banner that appears on the top of every page of your docs that aren't stable or latest.
-This banner has a text with a link redirecting the users to the latest version of your docs.
+A banner can be automatically displayed to notify viewers that there may be
+a more stable version of the documentation available. Specifically:
 
-This feature is disabled by default on new projects,
-you can enable it in the admin section of your docs (:guilabel:`Admin` > :guilabel:`Advanced Settings`).
+- When the ``latest`` version is being shown, and there's also a ``stable`` version active and not hidden,
+  then the banner will remind the viewer that some of the documented features may not yet be
+  available, and suggest that the viewer switch to the ``stable`` version.
+- When a version is being shown that is not the ``stable`` version, and there's a ``stable``
+  version available, then the banner will suggest that the viewer switch to the ``stable`` version
+  to see the newest documentation.
 
-.. note::
-
-   The banner will be injected in an HTML element with the ``main`` role or in the ``main`` tag.
-   For example:
-
-   .. code-block:: html
 
-      <div role="main">
-        <!-- The banner would be injected here -->
-        ...
-      </div>
+This feature is enabled by default on projects using the new beta addons.
+The beta addons can be enabled by using ``build.commands`` config key or via the new beta dashboard (https://beta.readthedocs.org) going to the admin section of your docs (:guilabel:`Admin` > :guilabel:`Advanced Settings`)
 
-   .. code-block:: html
-
-      <main>
-        <!-- The banner would be injected here -->
-        ...
-      </main>
+.. note::
 
+   An older version of this feature is currently only available to projects that have already enabled it.
+   When the updated feature development is finished the toggle setting will be enabled for all projects.
 
 Redirects on root URLs
 ----------------------