Docs: Relabel and move explanation and how-tos around OAuth (Diátaxis)

docs/user/connected-accounts.rst

@@ -1,28 +1,51 @@
-Connecting Your VCS Account
-===========================
+Connecting your Git repository
+==============================
+
+In this article, we explain how connecting your Read the Docs account to one of the supported Git providers
+automatically configures your Git repository and your Read the Docs project.
+
+✅️ Signed up with your Git provider?
+  If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab
+  credentials, you're all done. Your account is connected and the integration explained
+  below is enabled.
+⬇️ Signed up with your email address?
+  If you have signed up to Read the Docs with your email address,
+  you can add the connection to the Git provider afterwards.
+  Read more about how it works below.
+
 
 If you are going to import repositories from GitHub, Bitbucket, or GitLab,
-you should connect your Read the Docs account to your repository host first.
+we recommend that you connect your Read the Docs account to your repository provider.
+
 Connecting your account allows for:
 
-* Easier importing of your repositories
-* Automatically configure your repository :doc:`/integrations`
+* Easy import of your repositories
+* Automatic configuration of your repository :doc:`/integrations`
   which allow Read the Docs to build your docs on every change to your repository
-* Log into Read the Docs with your GitHub, Bitbucket, or GitLab credentials
+* Logging into Read the Docs with your GitHub, Bitbucket, or GitLab credentials
+
+
+.. seealso::
+
+   :doc:`/guides/connecting-git-account`
+     Here are the steps to connect your Read the Docs account to your Git repository provider.
+
+   :ref:`intro/import-guide:Manually import your docs`
+     Using a different provider?
+     Read the Docs still supports other providers such as Gitea or GitHub Enterprise.
+     In fact, any Git repository URL can be configured manually.
+
 
-If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab
-credentials, you're all done. Your account is connected.
+.. tip::
 
-To connect a social account, go to your :guilabel:`<Username dropdown>` > :guilabel:`Settings` > :guilabel:`Connected Services`.
-From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
-account. This process will ask you to authorize a connection to Read the Docs,
-that allows us to read information about and clone your repositories.
+   A single Read the Docs account can connect to many different Git providers.
+   This allows you to have a single login for all your various identities. 
 
 
 Permissions for connected accounts
 ----------------------------------
 
-Read the Docs does not generally ask for write permission to your repositories' code
+Read the Docs does not generally ask for *write* permission to your repository code
 (with one exception detailed below)
 and since we only connect to public repositories we don't need special permissions to read them.
 However, we do need permissions for authorizing your account
@@ -103,6 +126,7 @@ Bitbucket
 
 For similar reasons to those above for GitHub, we request permissions for:
 
+* Administering your repositories (to add a read-only deployment key)
 * Reading your account information including your email address
 * Read access to your team memberships
 * Read access to your repositories

docs/user/guides/administrators.rst

@@ -13,6 +13,7 @@ have a look at our :doc:`/tutorial/index`.
    :maxdepth: 1
 
    Connect your git repository <git-integrations>
+   Connect your Read the Docs account to your Git repository <connecting-git-account>
    Manage Custom Domains <custom-domains>
    Enable Canonical URLs <canonical-urls>
    technical-docs-seo-guide

docs/user/guides/connecting-git-account.rst

@@ -0,0 +1,22 @@
+How to connect your Read the Docs account to your Git repository
+================================================================
+
+If you are going to import repositories from GitHub, Bitbucket, or GitLab,
+you should connect your Read the Docs account to your repository host first.
+
+.. note::
+
+   If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab credentials,
+   you're all done. Your account is connected ✅️.
+
+To connect a social account, go to your :guilabel:`<Username dropdown>` > :guilabel:`Settings` > :guilabel:`Connected Services`.
+
+From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
+account. This process will ask you to authorize a connection to Read the Docs,
+that allows us to read information about and clone your repositories.
+
+
+.. seealso::
+
+   :doc:`/connected-accounts`
+     Learn about the permissions required for connecting accounts and the benefits of the OAuth integration.

docs/user/intro/import-guide.rst

@@ -33,7 +33,8 @@ these properties, and then click **Next** to
 Manually import your docs
 -------------------------
 
-If you do not have a connected account, you will need to select **Import Manually**
+If you have not :ref:`connected a Git provider account <guides/connecting-git-account:How to connect your Read the Docs account to your Git repository>`,
+you will need to select **Import Manually**
 and enter the information for your repository yourself. You will also need to
 manually configure the webhook for your repository as well. When importing your
 project, you will be asked for the repository URL, along with some other
@@ -53,6 +54,11 @@ project on Read the Docs. Go to your project's :guilabel:`Admin` > :guilabel:`In
 configure a new webhook, or see :ref:`our steps for webhook creation <integrations:Integration Creation>`
 for more information on this process.
 
+.. seealso::
+
+   :doc:`/guides/git-integrations`
+      Once you have imported your git project, use this guide to manually set up basic and additional integration.
+
 .. note::
     The ``Admin`` page can be found at ``https://readthedocs.org/dashboard/<project-slug>/edit/``.
     You can access all of the project settings from the admin page sidebar.