Merge pull request #8608 from readthedocs/clarify-docs

Clarify docs

Author: astrojuanlu

.github/CODEOWNERS

@@ -1 +1,3 @@
 *       @readthedocs/backend
+
+docs/*  @readthedocs/advocacy

docs/config-file/v2.rst

@@ -35,7 +35,7 @@ Below is an example YAML file which shows the most common configuration options:
          sphinx:
             configuration: docs/conf.py
 
-         # Optionally build your docs in additional formats such as PDF
+         # If using Sphinx, optionally build your docs in additional formats such as PDF
          # formats:
          #    - pdf
 
@@ -103,10 +103,11 @@ Example:
 formats
 ~~~~~~~
 
-Formats of the documentation to be built.
+Additional formats of the documentation to be built,
+apart from the default HTML.
 
 :Type: ``list``
-:Options: ``htmlzip``, ``pdf``, ``epub``
+:Options: ``htmlzip``, ``pdf``, ``epub``, ``all``
 :Default: ``[]``
 
 Example:
@@ -140,7 +141,8 @@ Example:
 
 .. warning::
 
-   ``pdf``, ``epub``, and ``htmlzip`` output is not supported when using MkDocs.
+   At the moment, only Sphinx supports additional formats.
+   ``pdf``, ``epub``, and ``htmlzip`` output is not yet supported when using MkDocs.
 
 python
 ~~~~~~

docs/intro/import-guide.rst

@@ -8,6 +8,8 @@ Importing Your Documentation
 To import a public documentation repository, visit your `Read the Docs dashboard`_ and click Import_.
 For private repositories, please use :doc:`Read the Docs for Business </commercial/index>`.
 
+Automatically import your docs
+------------------------------
 
 If you have :doc:`connected your Read the Docs account <../connected-accounts>` to GitHub, Bitbucket, or GitLab,
 you will see a list of your repositories that we are able to import.

docs/single_version.rst

@@ -13,16 +13,19 @@ Enabling
 ~~~~~~~~
 
 You can toggle the "Single Version" option on or off for your project in the Project Admin page.
-Check your :guilabel:`dashboard` for a list of your projects.
+Check your :term:`dashboard` for a list of your projects.
 
 Effects
 ~~~~~~~
 
-Links generated on Read the Docs will now point to the proper URL. For example,
-if pip was set as a "Single Version" project, then links to its documentation would point to
-``http://pip.readthedocs.io/`` rather than the default ``http://pip.readthedocs.io/en/latest/``.
+Links pointing to the :term:`root URL` of the project will now point to the proper URL.
+For example, if pip was set as a "Single Version" project,
+then links to its documentation would point to ``https://pip.readthedocs.io/``
+rather than redirecting to ``https://pip.readthedocs.io/en/latest/``.
 
-Documentation at ``/<language>/<default_version>/`` will still be served for backwards compatibility reasons.
-However, our usage of :ref:`custom_domains:Canonical URLs` should stop these from being indexed by Google.
+.. warning::
 
-.. _dashboard: https://readthedocs.org/dashboard/
+   Documentation at ``/<language>/<default_version>/`` will stop working.
+   Remember to set :ref:`custom_domains:Canonical URLs`
+   to tell search engines like Google what to index,
+   and to create :doc:`user-defined-redirects` to avoid broken incoming links.