diff --git a/docs/user/commercial/index.rst b/docs/user/commercial/index.rst
index eb98b394bcf..8107d0f6ef8 100644
--- a/docs/user/commercial/index.rst
+++ b/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 `__ is provided free of charge.
+In order to get started quickly, you can start a `free 30-day trial `__ to test out the platform.
.. seealso::
- `Read the Docs website: Features `__
- A high-level overview of platform features is available on our website, and the
+ `Read the Docs features `__
+ A high-level overview of platform features, and the
`pricing page `__ has a feature breakdown by subscription level.
- `Read the Docs website: 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 `__.
@@ -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.
diff --git a/docs/user/commercial/organizations.rst b/docs/user/commercial/organizations.rst
index 746d939ae88..c486da13f0c 100644
--- a/docs/user/commercial/organizations.rst
+++ b/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
~~~~~~~
diff --git a/docs/user/commercial/privacy-level.rst b/docs/user/commercial/privacy-level.rst
index b9db95e4f92..25dd1afa743 100644
--- a/docs/user/commercial/privacy-level.rst
+++ b/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.
diff --git a/docs/user/commercial/sharing.rst b/docs/user/commercial/sharing.rst
index 069c8948f33..28ccc5eacb0 100644
--- a/docs/user/commercial/sharing.rst
+++ b/docs/user/commercial/sharing.rst
@@ -3,37 +3,36 @@ 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
---------------
@@ -41,7 +40,7 @@ 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 ``.
+The header has the form ``Authorization: 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 ";
+
+ # 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;
+ }
+ }
diff --git a/docs/user/index.rst b/docs/user/index.rst
index 17724383e61..020874322e5 100644
--- a/docs/user/index.rst
+++ b/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