Docs: Relabel Organizations as Explanation (Diátaxis) (#9836)

* WIP: Rephrase Organization as an explanation article, include current how-to guide for teams in this work * Apply suggestions from code review @ericholscher Co-authored-by: Eric Holscher <[email protected]> * Change heading of Organizations article Co-authored-by: Eric Holscher <[email protected]>
readthedocs · Jan 3, 2023 · 9c9500e · 9c9500e
1 parent ed88ca7
commit 9c9500e
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 6 deletions.
diff --git a/docs/user/commercial/organizations.rst b/docs/user/commercial/organizations.rst
@@ -1,15 +1,21 @@
-Organizations
--------------
+Organizations: permissions for projects and teams
+-------------------------------------------------
 
 .. include:: /shared/admonition-rtd-business.rst
 
-Organizations allow you to segment who has access to what projects in your company.
-Your company will be represented as an Organization,
-let's use ACME Corporation as our example.
+In this article, we explain how the *organizations* feature on Read the Docs allows you to manage access to your projects.
+On |com_brand|, your account is linked to an *organization*.
+Organizations allow you to define both individual and team permissions for your projects.
 
+In this article, we use ACME Corporation as our example organization.
 ACME has a few people inside their organization,
 some who need full access and some who just need access to one project.
 
+.. seealso::
+
+   :doc:`/guides/manage-read-the-docs-teams`
+     A step-by-step guide to managing teams.
+
 Member Types
 ~~~~~~~~~~~~
 

diff --git a/docs/user/guides/manage-read-the-docs-teams.rst b/docs/user/guides/manage-read-the-docs-teams.rst
@@ -1,6 +1,8 @@
 How to manage Read the Docs teams
 =================================
 
+.. include:: /shared/admonition-rtd-business.rst
+
 Read the Docs uses teams within an organization to group users and provide permissions to projects.
 This guide will cover how to do team management,
 including adding and removing people from teams.
@@ -38,4 +40,7 @@ Automating this process
 
 You can manage teams more easily using our :doc:`Single Sign-On </commercial/single-sign-on>` features.
 
-.. seealso:: Our infomation on :doc:`/commercial/organizations`.
+.. seealso::
+
+   :doc:`/commercial/organizations`
+     General information about the *organizations* feature.
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -85,6 +85,7 @@ to help you create fantastic documentation for your project.
    /subprojects
    /single_version
    /science
+   /commercial/organizations
 
 .. toctree::
    :maxdepth: 2