Update Business docs (#11635)

* Update Business docs

The main update here is a set of common approaches to customer sharing,
and made the Privacy Levels doc make more sense.

I also went through and patched up a few other pages

* Apply suggestions from code review

Co-authored-by: Manuel Kaufmann <[email protected]>

* Address feedback

---------

Co-authored-by: Manuel Kaufmann <[email protected]>

Author: ericholscher

docs/user/commercial/index.rst

@@ -4,35 +4,22 @@ Business hosting
 .. this page is currently moving towards becoming "About Read the Docs for Business"
 .. rather than an index of features.
 
-We offer |com_brand| for building and hosting commercial documentation.
+We offer |com_brand| for building and hosting documentation for private repositories.
 
-Our commercial solutions are provided as a set of subscriptions that are paid and managed through an online interface.
-In order to get started quickly and easily, a `trial option <https://about.readthedocs.com/pricing/>`__ is provided free of charge.
+In order to get started quickly, you can start a `free 30-day trial <https://about.readthedocs.com/pricing/>`__ to test out the platform.
 
 .. seealso::
 
-   `Read the Docs website: Features <https://about.readthedocs.com/about/>`__
-      A high-level overview of platform features is available on our website, and the
+   `Read the Docs features <https://about.readthedocs.com/features/>`__
+      A high-level overview of platform features, and the
       `pricing page <https://about.readthedocs.com/pricing/>`__ has a feature breakdown by subscription level.
 
-   `Read the Docs website: Company <https://about.readthedocs.com/company/>`__
-      Information about the company running Read the Docs, including our mission, team, and community.
-
-
 Commercial documentation solutions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In addition to providing the same features as |org_brand|,
 commercial subscriptions to Read the Docs add additional features and run on separate infrastructure.
 
-.. figure:: /img/community_in_business.png
-   :align: center
-   :scale: 50%
-
-   Read the Docs for Community and Business are a combined system:
-   All features developed for community benefit the business solution, and most solutions developed for business users
-   are implemented for the community.
-
 The following list is a high-level overview of the areas covered by |com_brand|.
 If you want a full feature breakdown, please refer to our `pricing page <https://about.readthedocs.com/pricing/>`__.
 
@@ -42,13 +29,6 @@ Private repositories and private documentation
     to restrict documentation access to certain users,
     or to share private documentation via private hyperlinks.
 
-Additional build resources
-    Do you have a complicated build process that uses large amounts
-    of CPU, memory, disk, or networking resources?
-    Commercial subscriptions offer more resources
-    which results in faster documentation build times.
-    We can also customize builders, such as with a GPU or multiple CPUs.
-
 Priority support
     We have a dedicated support team that responds to support requests during business hours.
 

docs/user/commercial/organizations.rst

@@ -3,24 +3,20 @@ Organizations
 
 .. include:: /shared/admonition-rtd-business.rst
 
-In this article, we explain how the *organizations* feature on Read the Docs allows you to manage access to your projects.
+In this article, we explain how the *organizations* feature 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
-~~~~~~~~~~~~
+Important objects
+~~~~~~~~~~~~~~~~~
 
-* **Owners** -- Get full access to both view and edit the Organization and all Projects
-* **Members** -- Get access to a subset of the Organization projects
+* **Owners** -- Get full access to both view and edit the organization and all projects
+* **Members** -- Get access to a subset of the organization projects
 * **Teams** -- Where you give members access to a set of projects.
 
 The best way to think about this relationship is:
@@ -35,10 +31,10 @@ The best way to think about this relationship is:
 Team types
 ~~~~~~~~~~
 
-You can create two types of Teams:
+You can create two types of teams:
 
-* **Admins** -- These teams have full access to administer the projects in the team. They are allowed to change all of the settings, set notifications, and perform any action under the **Admin** tab.
-* **Read Only** -- These teams are only able to read and search inside the documents.
+* **Admin** -- Team members have full access to administer the projects assigned to the team. Members are allowed to change all of the settings, set notifications, and perform any action under the :guilabel:`Admin` tab for each project.
+* **Read Only** -- Team members are only able to read the documentation of each project, and not able to change anything about each project.
 
 Example
 ~~~~~~~

docs/user/commercial/privacy-level.rst

@@ -1,20 +1,44 @@
-.. TODO: This is a super weird page..
+Privacy Levels
+--------------
 
-:orphan:
+.. include:: /shared/admonition-rtd-business.rst
 
-Project privacy level
----------------------
+Privacy levels allow you to set the visibility of your project and its versions.
+This allows you to specify what information is available to the public and what is private.
+Privacy can be controlled at the level of the project and each version,
+and nothing more granular (eg. specific directories or URLs) can be controlled.
 
-.. include:: /shared/admonition-rtd-business.rst
+Project privacy
+~~~~~~~~~~~~~~~
 
 By default, only users that belong to your organization can see the dashboard of your project and its builds.
-If you want users outside your organization and anonymous users to be able to see the dashboard of your project,
+If you want users outside your organization to be able to see the dashboard of your project,
 and the build output of *public versions* you can set the privacy level of your project to ``Public``.
 
-You can administer this in your :term:`dashboard` by navigating to :menuselection:`Admin --> Settings`
+You can set the project privacy level in your :term:`dashboard` by navigating to :menuselection:`Admin --> Settings`
 and changing :guilabel:`Privacy level` to `Public`.
 
-.. note::
+**Making a project public doesn't give access to any versions.**
+So if you want all your versions to be accessible,
+you need to configure those to be `Public` as well.
+
+Version privacy
+~~~~~~~~~~~~~~~
+
+Each version of your documentation can be set to either `Public` or `Private`.
+This allows you to control who can see the documentation for a specific version.
+
+* Documentation for public versions is 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 visited by people without viewing permissions.
+  If you want to share your docs temporarily, see :doc:`/commercial/sharing`.
+
+You can set the privacy level for each version in your :term:`dashboard` by navigating to :menuselection:`Versions --> $version ... Drop down --> Configure version` and changing :guilabel:`Privacy level` to `Public`.
+
+Recommended workflow
+~~~~~~~~~~~~~~~~~~~~
 
-   To control access to the documentation itself,
-   see :ref:`versions:Version states`.
+We recommend defaulting everything to private,
+and only making versions public when you are ready to share them with the world.
+This allows you to work on your documentation in private,
+and only share it when you are ready.

docs/user/commercial/sharing.rst

@@ -3,45 +3,44 @@ Sharing private documentation
 
 .. include:: /shared/admonition-rtd-business.rst
 
-You can share your project with users outside of your company:
+Sharing private documentation is useful for giving quick access to your documentation to users outside of your organization.
+It allows you to share specific projects or versions of a project with users who don't have access to your organization.
 
-* by sending them a *secret link*,
-* by giving them a *password*.
+Common sharing use cases include:
 
-These methods will allow them to view specific projects or versions of a project inside your organization.
+* Sharing a project with contractors or partners.
+* Sharing documentation for your product only to specific customers.
+* Embedding documentation in a SaaS application dashboard.
 
-Additionally, you can use a HTTP Authorization Header.
-This is useful to have access from a script.
-
-Enabling sharing
-----------------
+Creating a shared item
+----------------------
 
 * Go into your project's :guilabel:`Admin` page and click on :guilabel:`Sharing`.
 * Click on :guilabel:`New Share`
 * Select access type (secret link, password, or HTTP header token),
-  add an expiration date and a *Description* so you remember who you're sharing it with.
+  add an expiration date and a *Description* to help with managing access in the future.
 * Check ``Allow access to all versions?`` if you want to grant access to all versions,
   or uncheck that option and select the specific versions you want grant access to.
 * Click :guilabel:`Save`.
 * Get the info needed to share your documentation with other users:
 
-  * If you have selected secret link, copy the link that is generated
-  * In case of password, copy the link and password
-  * For HTTP header token, you need to pass the ``Authorization`` header in your HTTP request.
+  * **Secret link:** copy the link that is generated
+  * **Password:** copy the link and password
+  * **HTTP header token**: Copy the token, and then pass the ``Authorization`` header in your HTTP request.
 
 * Give that information to the person who you want to give access.
 
 .. note::
 
-   You can always revoke access in the same panel.
+   You can always revoke access by removing the sharing item in this page.
 
 Sharing methods
 ---------------
 
 Secret link
 ***********
 
-Once the person you send the link to clicks the link,
+Once the person you send the link to clicks it,
 they will have access to the documentation while their browser window is open.
 
 If you want to link to a specific page,
@@ -58,7 +57,7 @@ Password
 
 Once the person you send the link to clicks on the link, they will see
 an *Authorization required* page asking them for the password you
-generated. When the user enters the password, they will have access to
+generated. When the user enters the password, they will gain access to
 view your project.
 
 .. tip::
@@ -77,12 +76,12 @@ Token Authorization
 ~~~~~~~~~~~~~~~~~~~
 
 You need to send the ``Authorization`` header with the token on each HTTP request.
-The header has the form ``Authorization: Token <ACCESS_TOKEN>``.
+The header has the form ``Authorization: Token <TOKEN>``.
 For example:
 
 .. prompt:: bash $
 
-   curl -H "Authorization: Token 19okmz5k0i6yk17jp70jlnv91v" https://docs.example.com/en/latest/example.html
+   curl -H "Authorization: Token $TOKEN" https://docs.example.com/en/latest/example.html
 
 Basic Authorization
 ~~~~~~~~~~~~~~~~~~~
@@ -92,4 +91,73 @@ For example:
 
 .. prompt:: bash $
 
-   curl --url https://docs.example.com/en/latest/example.html --user '19okmz5k0i6yk17jp70jlnv91v:'
+   curl --url https://docs.example.com/en/latest/example.html --user '$TOKEN:'
+
+
+Typical sharing configurations
+------------------------------
+
+There are a few common ways to architect sharing,
+with trade offs between them,
+and you should choose the one that best fits your use case.
+
+Bulk passwords
+**************
+
+If you want to limit access to a group of users,
+you can create a password for each user,
+and then share the password with them.
+This allows users to access the documentation directly,
+but requires more management on your end.
+Any time a new user needs access or you want to remove access,
+you will need to generate a new password for them.
+
+Authenticated redirect
+**********************
+
+If you want to share documentation with a group of users,
+you need to authenticate those users against your own system first.
+The simplest way to do this is to create an authenticated redirect on your site,
+which then redirects to the Read the Docs :ref:`Secret link`.
+
+This should require very little customization,
+and will ensure that only authenticated users can access the documentation.
+The downside is that users won't be able to access the documentation directly from a bookmark,
+and will have to go through your site first.
+
+Authenticated proxy
+*******************
+
+If you want a more transparent experience for your users,
+you can create a proxy that authenticates users against your system,
+and then proxies the request to Read the Docs.
+This is more complex to set up,
+but will allow users to access the documentation directly from a bookmark,
+
+This approach would use a :ref:`HTTP Authorization Header` to authenticate users,
+and would be configured in your proxy server.
+
+Proxy example
+-------------
+
+Below is an example of how to configure Nginx to proxy requests to Read the Docs while adding the token in the `Authorization` header.
+
+.. code-block:: nginx
+
+   server {
+       listen 80;
+       server_name docs.example.com;
+
+       location / {
+           proxy_pass https://docs-example.readthedocs-hosted.com;
+
+           # Add Authorization header with the token
+           proxy_set_header Authorization "Token <TOKEN>";
+
+           # Optionally forward other headers
+           proxy_set_header Host $host;
+           proxy_set_header X-Real-IP $remote_addr;
+           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+           proxy_set_header X-Forwarded-Proto $scheme;
+       }
+   }

docs/user/index.rst

@@ -83,11 +83,11 @@ Read the Docs: documentation simplified
    :hidden:
    :caption: Business features
 
-   /commercial/index
    /commercial/organizations
    /commercial/single-sign-on
    /commercial/sharing
    /commercial/subscriptions
+   /commercial/privacy-levels
 
 .. toctree::
    :maxdepth: 2