diff --git a/conf.py b/conf.py
index 06b4c68a12..492aab59b7 100644
--- a/conf.py
+++ b/conf.py
@@ -152,6 +152,7 @@
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
+ 'diataxis': ('https://diataxis.fr/', None),
}
todo_include_todos = True
diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst
index d9f04526e2..1d4c15c1f1 100644
--- a/documentation/style-guide.rst
+++ b/documentation/style-guide.rst
@@ -102,6 +102,48 @@ Unix
The name of the operating system developed at AT&T Bell Labs in the early
1970s.
+Diátaxis
+========
+
+Python's documentation strives to follow the `Diátaxis `_
+framework. This means adapting the writing style according to the nature of
+the documentation that is being written. The framework splits
+documentation into four distinct types: tutorials, how-to guides, reference, and
+explanation.
+
+* :ref:`python:tutorial-index` should
+ be explicit and avoid making assumptions about the
+ reader's knowledge. The goal of a tutorial is to get the user writing
+ Python code as quickly as possible with clear logical steps. Explanations
+ and abstract concepts should be avoided. Please consult the Diátaxis guide on
+ :ref:`diataxis:tutorials` for more detail.
+
+* `Python how-to guides `_ are
+ designed to guide a user through a problem-field.
+ Both tutorials and how-to guides are instructional rather than explanatory
+ and should provide logical steps on how to complete a task. However,
+ how-to guides make more assumptions about the user's knoweldge and
+ focus on the user finding the best way to solve their own
+ particular problem.
+
+* :ref:`python:reference-index` should
+ be factual and succinct. The purpose of reference documentation is
+ to describe rather than to explain. Accuracy and consistency are key as
+ this type of documentation should be seen as an authoritative source.
+ :ref:`Code-examples` can be a useful way of achieving these
+ objectives.
+
+* Python explanations provide
+ a deeper level of understanding and are naturally more discursive. They aim
+ to deepen the reader's understanding and answer 'why' questions. They should
+ provide context, make connections between topics, and discuss alternative
+ opinions. There is no section dedicated to explanations but these can be
+ found throughout Python's documentation, for example the
+ :ref:`python:unicode-howto`
+
+Please consult the `Diátaxis `_ guide for more
+detail.
+
Affirmative tone
================
@@ -159,6 +201,8 @@ module (e.g. OS level pipe buffers filling up and stalling child processes),
these can be documented in a "Common Errors" section and cross-referenced
rather than repeated for every affected interface.
+.. _code-examples:
+
Code examples
=============