Merge pull request #9302 from benjaoming/triaging

Improve scoping of two potentially overlapping Triage sections

Author: benjaoming

docs/.rstcheck.cfg

@@ -1,6 +1,6 @@
 [rstcheck]
 ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post,http:put,http:delete
-ignore_roles=djangosetting,setting,featureflags,buildpyversions
+ignore_roles=djangosetting,setting,featureflags,buildpyversions,external+rtd:doc,external,external+rtd
 ignore_substitutions=org_brand,com_brand,:smile:,:arrows_counterclockwise:,:heavy_plus_sign:,:tada:,:heart:,:pencil2:
 # This error needs to be ignored for now
 # See: https://github.com/myint/rstcheck/issues/19

docs/conf.py

@@ -94,6 +94,9 @@
     "rtd": ("https://docs.readthedocs.io/en/stable/", None),
     "rtd-dev": ("https://dev.readthedocs.io/en/latest/", None),
 }
+# Redundant in Sphinx 5.0
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
+intersphinx_disabled_reftypes = ["std:doc"]
 myst_enable_extensions = [
     "deflist",
 ]

docs/dev/contribute.rst

@@ -87,15 +87,22 @@ projects, feel free to suggest the language on Transifex to start the process.
 
 .. _our projects on Transifex: https://www.transifex.com/projects/p/readthedocs/
 
-Triaging tickets
-----------------
+Triaging issues
+---------------
 
-Core team uses the following guidelines for issue triage on all of our projects.
-These guidelines describe the issue lifecycle, and what is required at each step
-of this lifecycle.
+Everyone is encouraged to help improving, refining, verifying and prioritizing
+issues on Github. The Read the Docs core :external+rtd:doc:`team` uses the following
+guidelines for issue triage on all of our projects. These guidelines describe
+the issue lifecycle step-by-step.
 
 .. note:: You will need Triage permission on the project in order to do this.
-          You can ask one of the members of the :doc:`team` to give you access.
+          You can ask one of the members of the :external+rtd:doc:`team` to give you access.
+
+.. tip:: Triaging helps identify problems and solutions and ultimately what
+         issues that are ready to be worked on. The core
+         :external+rtd:doc:`team` maintains a separate :doc:`/roadmap`
+         of prioritized issues - issues will only end up on that Roadmap after
+         they have been triaged.
 
 Initial triage
 ~~~~~~~~~~~~~~

docs/dev/roadmap.rst

@@ -12,19 +12,21 @@ Here, you will find several views into our roadmap:
 
 `Backlog <https://github.com/orgs/readthedocs/projects/156/views/4>`_
     Work that we have planned for future sprints. Items with an assigned
-    timeframe have generally been discussed already by the team. Iteams that do
+    timeframe have generally been discussed already by the team. Items that do
     not yet have a timeframe assigned are not yet a priority of the core team.
 
 The focus of the core team will be on roadmap and sprint items. These items are
 promoted from our backlog before each sprint begins.
 
 .. _GitHub Roadmap: https://github.com/orgs/readthedocs/projects/156/views/1
 
-Triaging issues
-~~~~~~~~~~~~~~~
+Triaging issues for the Roadmap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Much of this is already covered in our guide on :doc:`contribute`, however to
-summarize the important pieces:
+Issues are triaged before they are worked on, involving a number of steps that
+are covered in :doc:`/contribute`. Everyone can take part in helping to
+triage issues, read more in :ref:`contribute:Triaging issues`. Additionally, issues are
+considered for the Roadmap according to the following process:
 
 * New issues coming in will be triaged, but won't yet be considered part of our
   roadmap.

docs/user/localization.rst

@@ -51,7 +51,7 @@ It also gets included in the Read the Docs flyout:
 .. note::
     The default language of a custom domain is determined by the language of the
     parent project that the domain was configured on. See
-    :doc:`custom_domains` for more information.
+    :doc:`/custom-domains` for more information.
 
 .. note:: You can include multiple translations in the same repository,
           with same ``conf.py`` and ``.rst`` files,

docs/user/security.rst

@@ -69,7 +69,7 @@ The issue was found by the Read the Docs team.
 Version 5.14.0
 ~~~~~~~~~~~~~~
 
-:ref:`changelog:Version 5.14.0` fixes an issue where that affected new code that removed multiple slashes in URL paths. The issue allowed the creation of hyperlinks that looked like they would go to a documentation domain on Read the Docs (either `*.readthedocs.io` or a [custom docs domain](https://docs.readthedocs.io/en/stable/custom_domains.html)) but instead went to a different domain.
+:ref:`changelog:Version 5.14.0` fixes an issue where that affected new code that removed multiple slashes in URL paths. The issue allowed the creation of hyperlinks that looked like they would go to a documentation domain on Read the Docs (either `*.readthedocs.io` or a :doc:`custom docs domain </custom-domains>`)) but instead went to a different domain.
 
 This issue was reported by Splunk after it was reported by a security audit.
 

docs/user/single_version.rst

@@ -26,6 +26,6 @@ rather than redirecting to ``https://pip.readthedocs.io/en/latest/``.
 .. warning::
 
    Documentation at ``/<language>/<default_version>/`` will stop working.
-   Remember to set :ref:`custom_domains:Canonical URLs`
+   Remember to set :doc:`canonical URLs </canonical-urls>`
    to tell search engines like Google what to index,
    and to create :doc:`user-defined-redirects` to avoid broken incoming links.