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

docs/user/guides/administrators.rst

@@ -22,4 +22,5 @@ have a look at our :doc:`/tutorial/index`.
    pdf-non-ascii-languages
    importing-private-repositories
    Setup Build Notifications <build-notifications>
+   subprojects
    Configure Pull Request Builds <pull-requests>

docs/user/guides/subprojects.rst

@@ -0,0 +1,32 @@
+How To Add a Subproject
+=======================
+
+This guide shows you how to add a subproject to your main project.
+
+.. seealso::
+
+   :doc:`/subprojects`
+      Read more about what the subproject feature can do and how it works.
+
+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.
+
+Subproject 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 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``.

docs/user/index.rst

@@ -82,6 +82,7 @@ to help you create fantastic documentation for your project.
    /custom-domains
    /pull-requests
    /downloadable-documentation
+   /subprojects
 
 .. toctree::
    :maxdepth: 2
@@ -231,7 +232,6 @@ out of your documentation and Read the Docs.
    :glob:
    :caption: Advanced features
 
-   subprojects
    single_version
    flyout-menu
    feature-flags

docs/user/subprojects.rst

@@ -1,30 +1,30 @@
-Subprojects
-===========
+Organizing multiple projects in one site: Subprojects
+=====================================================
 
 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.
 
-For example, a parent project, ``Foo`` is set up with a subproject, ``Bar``. The
-documentation for ``Foo`` will be available at:
+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:
 
 https://foo.readthedocs.io/en/latest/
 
-The documentation for ``Bar`` will be available under this same path:
+The documentation for ``bar`` will be available under this same path:
 
 https://foo.readthedocs.io/projects/bar/en/latest/
 
-Adding a subproject
--------------------
+.. seealso::
 
-In the admin dashboard for your project, select "Subprojects" from the menu.
-From this page you can add a subproject by typing in the project slug.
+   :doc:`/guides/subprojects`
 
-Subproject aliases
-~~~~~~~~~~~~~~~~~~
-
-You can use an alias for the subproject when it is created. This allows you to override the URL that is used to access it, giving more configurability to how you want to structure your projects.
 
 Sharing a custom domain
 -----------------------
@@ -34,8 +34,8 @@ 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.
 
-If the example project ``Foo`` was set up with a custom domain,
-``docs.example.com``, the URLs for projects ``Foo`` and ``Bar`` would
+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: https://docs.example.com/en/latest/ and
 https://docs.example.com/projects/bar/en/latest/
 
@@ -46,6 +46,18 @@ Adding a custom domain to a subproject is not allowed,
 since your documentation will always be served from
 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.
+
+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.
+
+When the user navigates to a subproject,
+they are presented with a :term:`flyout menu` matching the subproject's versions and :doc:`/downloadable-documentation`.
+
 Search
 ------