Docs: simplify "Add project" page (#11559)

* Docs: simplify "Add project" page * Rename it to `add-project.html` * Always use "add" instead of "import" * Explain the process using the new dashboard * Make usage of a numbered list of steps intead of a single paragraph * Remove irrelevant content and focus on _adding a project_ * Keep relevant links under "See also" sections * Docs: rename `import-guide` to `add-project` * Typo * Delete old images * Apply suggestions from code review Co-authored-by: Anthony <aj@ohess.org> Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> * Rephrase sentence --------- Co-authored-by: Anthony <aj@ohess.org> Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>
readthedocs · Sep 12, 2024 · bc847f9 · bc847f9
1 parent b30b665
commit bc847f9
Show file tree

Hide file tree

Showing 13 changed files with 94 additions and 112 deletions.
diff --git a/docs/user/_static/images/first-steps/admin-panel.png b/docs/user/_static/images/first-steps/admin-panel.png
diff --git a/docs/user/_static/images/first-steps/import-a-repository.png b/docs/user/_static/images/first-steps/import-a-repository.png
diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst
@@ -11,12 +11,21 @@ so that you have a reference for how we're using them.
       In some scenarios, they exist as two separate platforms.
       Read the Docs is a combined CI/CD platform made for documentation.
 
+   configuration file
+      YAML configuration file (e.g. ``.readthedocs.yaml``) that configures the build process of your project on Read the Docs.
+
+      .. seealso::
+
+         :doc:`/config-file/index`
+            Practical steps to add a configuration file to your documentation project.
+
+
    dashboard
       The "admin" site where Read the Docs projects are managed and configured.
       This varies for our two properties:
 
-       * |com_brand|: https://readthedocs.com/dashboard/.
-       * |org_brand|: https://readthedocs.org/dashboard/.
+       * |com_brand|: https://app.readthedocs.com/dashboard/
+       * |org_brand|: https://app.readthedocs.org/dashboard/
 
    default version
       Projects have a *default version*, usually the latest stable version of a project.
@@ -145,4 +154,10 @@ so that you have a reference for how we're using them.
       * Git providers have webhooks which are special URLs that Read the Docs can call in order to notify about documentation builds.
       * Read the Docs has a unique webhook for each project that the Git provider calls when changes happen in Git.
 
-      See also: :doc:`/guides/setup/git-repo-manual` and :doc:`/build-notifications`
+      .. seealso::
+
+         :doc:`/guides/setup/git-repo-manual`
+            Manually configuration for Git repositories.
+
+         :doc:`/build-notifications`
+            Receive notifications when your documentation builds fail.
diff --git a/docs/user/guides/importing-private-repositories.rst b/docs/user/guides/importing-private-repositories.rst
@@ -8,7 +8,7 @@ Here is how you set it up.
 
 ✅️ Logged in with |git_providers_or|?
   If you signed up or logged in to Read the Docs with your |git_providers_or| credentials,
-  *all you have to do* is to use the normal :doc:`project import </intro/import-guide>`.
+  *all you have to do* is to use the normal :doc:`project import </intro/add-project>`.
   Your Read the Docs account is connected to your Git provider and
   will let you choose from private Git repositories and configure them for you.
 

diff --git a/docs/user/guides/setup/git-repo-automatic.rst b/docs/user/guides/setup/git-repo-automatic.rst
@@ -26,7 +26,7 @@ the integration will automatically be configured on the Read the Docs project an
 Here is an outline of what happens:
 
 #. A list of repositories that you have access to are automatically listed on Read the Docs' project import.
-#. You choose a Git repository from the list (see :doc:`/intro/import-guide`).
+#. You choose a Git repository from the list (see :doc:`/intro/add-project`).
 #. Data about the repository is now fetched using the account connection and you are asked to confirm the setup.
 #. When Read the Docs creates your project,
    it automatically sets up an integration with the Git provider,
@@ -55,7 +55,7 @@ including the ones that were automatically created.
 
 .. seealso::
 
-   :ref:`intro/import-guide:Manually import your docs`
+   :ref:`intro/add-project:Manually add your project`
      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.
@@ -80,7 +80,7 @@ By granting Read the Docs the requested permissions,
 we are issued a secret OAuth token from your Git provider.
 
 Using the secret token,
-we can automatically configure the repository that you select in the :doc:`project import </intro/import-guide>`.
+we can automatically configure repositories during :doc:`project creation </intro/add-project>`.
 We also use the token to send back build statuses and preview URLs for :doc:`pull requests </pull-requests>`.
 
 .. _OAuth: https://en.wikipedia.org/wiki/OAuth

diff --git a/docs/user/guides/setup/monorepo.rst b/docs/user/guides/setup/monorepo.rst
@@ -36,10 +36,8 @@ A custom build configuration file path is applied to all versions of your docume
 Adding an additional project from the same repository
 -----------------------------------------------------
 
-Once you have added the first project from the :ref:`Import Wizard <intro/import-guide:Automatically import your docs>`,
-it will show as if it has already been imported and cannot be imported again.
-In order to add another project with the same repository,
-you will need to use the :ref:`Manual Import <intro/import-guide:Manually import your docs>`.
+Once you have added the first project from the :ref:`Import Wizard <intro/add-project:Automatically add your project>`,
+you will need to repeat this process again to add the additional project from the same repository.
 
 Setting the custom build configuration file
 -------------------------------------------

diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -9,7 +9,7 @@ Read the Docs: documentation simplified
    /tutorial/index
    /intro/getting-started-with-sphinx
    /intro/getting-started-with-mkdocs
-   /intro/import-guide
+   /intro/add-project
    /examples
 
 .. toctree::

diff --git a/docs/user/intro/add-project.rst b/docs/user/intro/add-project.rst
@@ -0,0 +1,62 @@
+Adding a documentation project
+==============================
+
+.. meta::
+   :description lang=en: Add your existing documentation from a Git repository into Read the Docs.
+
+This page takes you through the process of adding a documentation project to Read the Docs.
+If you have :doc:`connected your Read the Docs account </guides/connecting-git-account>` to GitHub, Bitbucket or GitLab you will be able to add your project automatically.
+Otherwise, you will need to add it manually and perform some extra steps.
+
+Automatically add your project
+------------------------------
+
+#. Go to your :term:`dashboard`.
+#. Click on :guilabel:`Add project`.
+#. Type the name of the respository you want to add and click on it.
+#. Click on :guilabel:`Continue`.
+#. Edit any of the pre-filled fields with information of the repository.
+#. Click on :guilabel:`Next`.
+#. Add a :term:`configuration file` to your repository if it's doesn't exist yet.
+#. Click on :guilabel:`This file exists`.
+
+Manually add your project
+-------------------------
+
+#. Go to your :term:`dashboard`.
+#. Click on :guilabel:`Add project`.
+#. Click on :guilabel:`Configure manually`.
+#. Click on :guilabel:`Continue`.
+#. Fill all the fields of the form.
+#. Click on :guilabel:`Next`.
+#. Add a :term:`configuration file` to your repository if it's doesn't exist yet.
+#. Click on :guilabel:`This file exists`.
+
+Once your project is created, you'll need to manually configure the repository webhook if you would like to have new changes trigger builds for your project on Read the Docs.
+
+.. seealso::
+
+   :doc:`/guides/setup/git-repo-manual`
+      Additional setup steps required for manually created projects. This guide covers setting up SSH keys and webhook integrations.
+
+
+What's next
+-----------
+
+Once your documentation project is created, a build will be triggered.
+It will automatically fetch the code from your repository and build the documentation.
+You can see the logs for the build process from your :term:`dashboard`.
+
+.. seealso::
+
+   :doc:`/builds`
+      Explanation about the build process.
+
+   :doc:`/config-file/index`
+      Practical steps to add a configuration file to your documentation project.
+
+   :doc:`/versions`
+      Manage multiple versions of your documentation project.
+
+If you have any trouble, don't hesitate to reach out to us.
+The :doc:`support </support>` page has more information on getting in touch.
diff --git a/docs/user/intro/getting-started-with-mkdocs.rst b/docs/user/intro/getting-started-with-mkdocs.rst
@@ -22,7 +22,7 @@ It has many great features including:
 Quick start
 -----------
 
-.. seealso:: If you already have a Mkdocs project, check out our :doc:`/intro/import-guide` guide.
+.. seealso:: If you already have a Mkdocs project, check out our :doc:`/intro/add-project` guide.
 
 Assuming you have Python already, `install MkDocs`_:
 
@@ -59,7 +59,7 @@ You can make changes to your Markdown files and your docs will automatically reb
    Your MkDocs project is built
 
 Once you have your documentation in a public repository such as GitHub, Bitbucket, or GitLab,
-you can start using Read the Docs by :doc:`importing your docs </intro/import-guide>`.
+you can start using Read the Docs by :doc:`adding a project </intro/add-project>`.
 
 .. _install MkDocs: https://www.mkdocs.org/user-guide/installation/
 

diff --git a/docs/user/intro/getting-started-with-sphinx.rst b/docs/user/intro/getting-started-with-sphinx.rst
@@ -22,7 +22,7 @@ check out :doc:`/tutorial/index`.
 Quick start
 -----------
 
-.. seealso:: If you already have a Sphinx project, check out our :doc:`/intro/import-guide` guide.
+.. seealso:: If you already have a Sphinx project, check out our :doc:`/intro/add-project` guide.
 
 Assuming you have Python already, :doc:`install Sphinx <sphinx:usage/installation>`:
 
@@ -68,7 +68,7 @@ Open this file in your web browser to see your docs.
 
 Edit your files and rebuild until you like what you see, then commit your changes and push to your public repository.
 Once you have Sphinx documentation in a public repository, you can start using Read the Docs
-by :doc:`importing your docs </intro/import-guide>`.
+by :doc:`adding a project </intro/add-project>`.
 
 .. warning::
 

diff --git a/docs/user/intro/import-guide.rst b/docs/user/intro/import-guide.rst
diff --git a/docs/user/reference/git-integration.rst b/docs/user/reference/git-integration.rst
@@ -9,7 +9,7 @@ Connecting your account provides the following features:
 
 🔁️ List your projects
   Select a project to automatically import from all your Git repositories and organizations.
-  See: :doc:`/intro/import-guide`.
+  See: :doc:`/intro/add-project`.
 
 ⚙️ Automatic configuration
   Have your Git repository automatically configured with your Read the Docs :term:`webhook`,

diff --git a/docs/user/tutorials/index.rst b/docs/user/tutorials/index.rst
@@ -19,7 +19,7 @@ Tutorials
   This is especially popular because of its default of using Markdown.
   This tool is well-supported on our platform and that's why we have a tutorial.
 
-⏩️ :doc:`/intro/import-guide`
+⏩️ :doc:`/intro/add-project`
   If you already wrote your documentation,
   this guide will help you get started at the most natural point:
   importing an existing documentation project.
@@ -39,6 +39,6 @@ Tutorials
    /tutorial/index
    /intro/getting-started-with-sphinx
    /intro/getting-started-with-mkdocs
-   /intro/import-guide
+   /intro/add-project
    /config-file/index
    /examples