Docs: Split Subprojects in Explanation and How-to (Diátaxis)

docs/user/guides/subprojects.rst

@@ -1,5 +1,5 @@
-How To Add a Subproject
-=======================
+How to manage subprojects
+=========================
 
 This guide shows you how to add a subproject to your main project.
 
@@ -14,24 +14,30 @@ Adding a subproject
 In the admin dashboard for your project, select :guilabel:`Subprojects` from the menu.
 From this page you can add a subproject by typing in the project slug.
 
+Immediately after adding the subproject, its default version will be visible from the link displayed in the list of subprojects.
+
 .. note::
 
    * On |org_brand|, you need to be maintainer of a subproject in order to choose it from your main project.
    * On |com_brand|, you need to have admin access to the subproject in order to choose it from your main project.
 
-Subproject aliases
-~~~~~~~~~~~~~~~~~~
+Editing a subproject
+--------------------
+
+You can edit a subproject at any time by clicking :guilabel:`|:memo:|` in the list of subprojects.
+On the following page, it's possible to both change the alias and source project.
+Click :guilabel:`Update subproject` to save your changes.
+
+What is visible in ``/projects/<subproject-alias>/`` will be updated immediately when you save your changes.
+
+
+Deleting a subproject
+---------------------
 
-You can choose an alias for the subproject when it is created.
-This allows you to override the URL that is used to access it,
-giving more control over how you want to structure your projects.
+You can edit a subproject at any time by clicking :guilabel:`|:memo:|` in the list of subprojects.
+On the edit page, click :guilabel:`Delete subproject`.
 
-You can set your subproject's project name and :term:`slug` however you want,
-but we suggest prefixing it with the name of the main project.
+Your subproject will be removed immediately and it will stop redirecting from its own domain.
 
-Typically, a subproject is created with a ``<mainproject>-`` prefix,
-for instance if the main project is called ``foo`` and the subproject is called ``bar``,
-then the subproject's Read the Docs project name will be ``foo-bar``.
-When adding the subproject,
-the alias is set to ``bar`` and the project's URL becomes
-``foo.readthedocs.io/projects/bar``.
+Deleting a subproject does not mean to completely remove that project.
+It is solely about removing the reference from the main project.

docs/user/subprojects.rst

@@ -1,46 +1,74 @@
 Subprojects: host multiple projects on a single domain
-=====================================================
+======================================================
 
-Projects can be configured in a nested manner, by configuring a project as a
-*subproject* of another project. This allows for documentation projects to share
-a search index and a namespace or custom domain, but still be maintained
-independently.
+In this article, you can learn more about how several documentation projects can be combined and presented to the reader on the same website.
+
+Read the Docs projects can be configured to make other *subprojects* available on the website of the *main project*.
+This allows for documentation projects to share a search index and a namespace or custom domain,
+but still be maintained independently.
 
 This is useful for:
 
 * Organizations that need all their projects visible in one documentation portal or landing page
 * Projects that document and release several packages or extensions
 * Organizations or projects that want to have a common search function for several sets of documentation
 
-For example, a parent project, ``foo`` is set up with a subproject, ``bar``. The
-documentation for ``foo`` will be available at:
+For example, a parent project, ``example-project`` is set up with a subproject, ``plugin``. The
+documentation for ``example-project`` will be available at:
 
-https://foo.readthedocs.io/en/latest/
+https://example-project.readthedocs.io/en/latest/
 
-The documentation for ``bar`` will be available under this same path:
+The documentation for ``plugin`` will be available under this same path:
 
-https://foo.readthedocs.io/projects/bar/en/latest/
+https://example-project.readthedocs.io/projects/plugin/en/latest/
 
 .. seealso::
 
    :doc:`/guides/subprojects`
 
-
 Sharing a custom domain
 -----------------------
 
-Projects and subprojects can also be used to share a custom domain with a number
-of projects. To configure this, one project should be established as the parent
-project. This project will be configured with a custom domain. Projects can then
-be added as subprojects to this parent project.
+Projects and subprojects can be used to share a custom domain.
+To configure this, one project should be established as the main project.
+This project will be configured with a custom domain.
+Other projects are then added as subprojects to the main project.
 
 If the example project ``foo`` was set up with a custom domain,
 ``docs.example.com``, the URLs for projects ``foo`` and ``bar`` would
-respectively be at: 
+respectively be at:
 
 * `foo`: https://docs.example.com/en/latest/
 * `bar`: https://docs.example.com/projects/bar/en/latest/
 
+.. note::
+
+   The terms "parent" and "child" are also used,
+   where the main project is the parent and all subprojects are a child.
+   You can **not** have a child of a child,
+   meaning that you cannot add a subproject to a subproject.
+
+Using aliases
+-------------
+
+You can choose an alias for the subproject when it is created.
+This allows you to override the URL that is used to access it,
+giving more control over how you want to structure your projects.
+
+You can set your subproject's project name and :term:`slug` however you want,
+but we suggest prefixing it with the name of the main project.
+
+Typically, a subproject is created with a ``<mainproject>-`` prefix,
+for instance if the main project is called ``foo`` and the subproject is called ``bar``,
+then the subproject's Read the Docs project name will be ``foo-bar``.
+When adding the subproject,
+the alias is set to ``bar`` and the project's URL becomes
+``foo.readthedocs.io/projects/bar``.
+
+When you add a subproject,
+the subproject will not be directly available anymore from its own domain.
+For instance, ``subproject.readthedocs.io/`` will redirect to ``mainproject.readthedocs.io/projects/subproject``.
+
 Custom domain on subprojects
 ----------------------------
 
@@ -51,14 +79,18 @@ the domain of the parent project.
 Separate release cycles
 -----------------------
 
-When several projects are documented in the same space, it's common that they follow separate release cycles.
+By using subprojects,
+you can present the documentation of several projects
+even though they have separate release cycles.
 
-We recommend that the documentation follows the release cycle of whatever it is documenting.
-By using subprojects, you can present your documentation for several projects with separate release cycles.
-This is solved by having the :term:`flyout menu` active for the project that's viewed.
+Your main project may have its own versions and releases,
+while all of its subprojects maintain their own individual versions and releases.
+We recommend that documentation follows the release cycle of whatever it is documenting,
+meaning that your subprojects should be free to follow their own release cycle.
 
+This is solved by having an individual :term:`flyout menu` active for the project that's viewed.
 When the user navigates to a subproject,
-they are presented with a :term:`flyout menu` matching the subproject's versions and :doc:`/downloadable-documentation`.
+they are presented with a flyout menu matching the subproject's versions and :doc:`/downloadable-documentation`.
 
 Search
 ------