Custom domain doc improvements (#10719)

* Drop custom domain mermaid graphic

I don't feel this improves the user understanding of how custom domains
work, and seems to be a pain to update to make it more helpful. Removing
this for now.

* Explain our default subdomains better

Mention organization name as well, but don't surface the word "slug" as
"name" is more relateable to the user.

* Remove custom domain guidance for open source projects

This stands out as misplaced content for our feature page on custom domains.

* Rework set up notes and "how custom domains work" into features section

This drops "how custom domains work", which was some duplicate content
of our how to set up custom domains guide. Content that leaned more
towards describing the features of custom domains was reworked into a
feature section that lists the features that make up custom domain
support.

* Backwards link syntax

* Don't use page title for CDN doc

* Remove missed extra word

Co-authored-by: Santos Gallegos <[email protected]>

* Update docs/user/custom-domains.rst

Co-authored-by: Eric Holscher <[email protected]>

---------

Co-authored-by: Santos Gallegos <[email protected]>
Co-authored-by: Eric Holscher <[email protected]>

docs/user/custom-domains.rst

@@ -1,105 +1,57 @@
 Custom domains
 ==============
 
-You can serve your documentation project from your own domain,
+By configuring a *custom domain* for your project,
+your project can serve documentation from a domain you control,
 for instance ``docs.example.com``.
 This is great for maintaining a consistent brand for your product and its documentation.
 
 .. _default-subdomain:
 
 .. rubric:: Default subdomains
 
-*By default*, your documentation is served from a Read the Docs *subdomain* using the project's :term:`slug`:
+*Without a custom domain configured*,
+your project's documentation is served from a Read the Docs domain using a unique subdomain for your project:
 
-* ``<slug>.readthedocs.io`` for |org_brand|
-* ``<slug>.readthedocs-hosted.com`` for |com_brand|.
+* ``<project name>.readthedocs.io`` for |org_brand|.
+* ``<organization name>-<project name>.readthedocs-hosted.com`` for |com_brand|.
+  The addition of the organization name allows multiple organizations to have projects with the same name.
 
 .. seealso::
 
-    :doc:`/guides/custom-domains`
-        Information on creating and managing custom domains,
-        and common configurations you might use to set up your domain
+   :doc:`/guides/custom-domains`
+      How to create and manage custom domains for your project.
 
-How custom domains work
------------------------
+Features
+--------
 
-To use a custom domain, two actions are needed from you:
+Automatic SSL
+   SSL certificates are automatically issued through Cloudflare for every custom domain.
+   No extra set up is required beyond configuring your project's custom domain.
 
-#.  Enter the domain in your Read the Docs project's :guilabel:`Admin`
-#.  Update your DNS provider with a new DNS entry. The name and value of the DNS entry is found in Read the Docs' :guilabel:`Admin`.
+CDN caching
+   Response caching is provided through a :doc:`CDN </reference/cdn>` for all documentation projects,
+   including projects using a custom domain.
+   CDN caching improves page response time for your documentation's users,
+   and the CDN edge network provides low latency response times regardless of location.
 
-Once the new DNS record has propagated,
-Read the Docs automatically issues an SSL certificate through Cloudflare and starts serving your documentation.
+Multiple domains
+   Projects can be configured to be served from multiple domains,
+   which always includes the :ref:`project's default subdomain <default-subdomain>`.
+   Only one domain can be configured as the canonical domain however,
+   and any requests to non-canonical domains and subdomains will redirect to the canonical domain.
 
-.. image:: img/mermaid-custom-domains.png
-   :alt: Diagram of the process of adding a custom domain on Read the Docs
-
-..
-   We have generated an PNG version of the following diagram using mermaid.live
-   Firstly, we generate an SVG, then we render it in a browser, then we take a screenshot,
-   then we paste it into GIMP or similar and make the background transparent.
-
-   If you wish to sketch diagrams locally, you can add sphinxcontrib-mermaid to
-   this project's extensions and keep using the below code.
-
-   SVG does not work because it embeds fontawesome from CDN (which is blocked by CSP)
-
-   PLEASE KEEP THIS SOURCE CODE UPDATED
-   .. mermaid::
-
-       graph TD
-           subgraph rtd [On Read the Docs]
-             A(fa:fa-pencil Add docs.example.com as Custom Domain)
-           end
-           subgraph dns [On your domain's DNS administration]
-             B(fa:fa-pencil Edit/add a DNS entry for docs.example.com<br>making it point to Read the Docs)
-           end
-
-           rtd & dns-->C(fa:fa-spinner Wait for DNS propagation.<br>Usually just a few minutes)
-
-           direction LR
-           subgraph automatic [fa:fa-paper-plane The rest is handled automatically]
-             direction TB
-             D(fa:fa-spinner The next time your project is built,<br>its Canonical URLs use docs.example.com)
-             D-->E(Visit https://docs.example.com)
-             E-->F(fa:fa-lock Correct SSL Certificate <br>automatically used)
-             F-->G(fa:fa-check Read the Docs knows<br> to serve your project <br>at docs.example.com)
-           end
-
-           C-->automatic
-
-
-Your documentation can have multiple secondary domains but only one **canonical** domain name.
-Additional domains or subdomains will redirect to the canonical domain.
-
-To make this work, Read the Docs generates a special text that you are responsible for copy-pasting to your domain's DNS.
-In most cases, the ``CNAME`` record is used.
-This is all that's needed for a web browser to resolve your domain name to Read the Docs' servers and for our servers to match the right documentation project.
-You can find step-by-step instructions for this in :doc:`/guides/custom-domains`.
-
-Read the Docs uses a :doc:`/reference/cdn` to host and serve your documentation pages.
-This final step isn't changed by a custom domain
-and therefore the response times are unaffected as the delivery of resources happens through the same CDN setup.
-
-Considerations for custom domain usage
---------------------------------------
-
-Some open source projects have seen their domains expire.
-Even prominent ones.
-**It's important that you give the responsibility for managing your domain to someone reliable in your organization.**
-
-The **canonical domain** feature allows you to have several domains and the canonical domain will be indexed by search engines.
-The domain that you choose as your canonical domain is by far the most important one.
-If you lose the canonical domain,
-someone else can set up a website that search results will end up referring to.
+Canonical domains
+   The canonical domain configures the primary domain the documentation will serve from,
+   and also sets the domain search engines use for search results when hosting from multiple domains.
+   Projects can only have one canonical domain,
+   which is the :ref:`project's default subdomain <default-subdomain>` if no other canonical domain is defined.
 
 .. seealso::
 
-   In a URL, both the domain and the path (``https://<domain>/<path>``) are important.
-   In combination, they are referred to as the *canonical URL* of a resource.
-
-   Most documentation projects are versioned.
-   Therefore, it's important to ensure that incoming links and search engine results point to the canonical URL of the resource
-   and not a specific version that becomes outdated.
+   :doc:`/canonical-urls`
+      How canonical domains affect your project's canonical URL,
+      and why canonical URLs are important.
 
-   To learn more about canonical URLs, see: :doc:`/canonical-urls`
+   :doc:`/subprojects`
+      How to share a custom domain between multiple projects.