Fixed #26003 -- Added "how the documentation is organized" sections.

Thanks Daniele Procida for coauthoring.

2 files changed, 75 insertions, 0 deletions

diff --git a/docs/index.txt b/docs/index.txt
index 34cc74fb95..c10cdd9af5 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -31,6 +31,30 @@ Having trouble? We'd like to help!
 .. _IRC logs: http://django-irc-logs.com/
 .. _ticket tracker: https://code.djangoproject.com/
 
+How the documentation is organized
+==================================
+
+Django has a lot of documentation. A high-level overview of how it's organized
+will help you know where to look for certain things:
+
+* :doc:`Tutorials </intro/index>` take you by the hand through a series of
+  steps to create a Web application. Start here if you're new to Django or Web
+  application development. Also look at the ":ref:`index-first-steps`" below.
+
+* :doc:`Topic guides </topics/index>` discuss key topics and concepts at a
+  fairly a fairly high level and provide useful background information and
+  explanation.
+
+* :doc:`Reference guides </ref/index>` contain technical reference for APIs and
+  other aspects of Django's machinery. They describe how it works and how to
+  use it but assume that you have a basic understanding of key concepts.
+
+* :doc:`How-to guides </howto/index>` are recipes. They guide you through the
+  steps involved in addressing key problems and use-cases. They are more
+  advanced than tutorials and assume some knowledge of how Django works.
+
+.. _index-first-steps:
+
 First steps
 ===========
 
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt
index f8e5b4f1a8..13bfe88290 100644
--- a/docs/internals/contributing/writing-documentation.txt
+++ b/docs/internals/contributing/writing-documentation.txt
@@ -65,6 +65,57 @@ Primer <sphinx:rst-primer>`. After that, you'll want to read about the
 :ref:`Sphinx-specific markup <sphinx:sphinxmarkup>` that's used to manage
 metadata, indexing, and cross-references.
 
+How the documentation is organized
+----------------------------------
+
+The documentation is organized into several categories:
+
+* :doc:`Tutorials </intro/index>` take the reader by the hand through a series
+  of steps to create something.
+
+  The important thing in a tutorial is to help the reader achieve something
+  useful, preferably as early as possible, in order to give them confidence.
+
+  Explain the nature of the problem we're solving, so that the reader
+  understands what we're trying to achieve. Don't feel that you need to begin
+  with explanations of how things work - what matters is what the reader does,
+  not what you explain. It can be helpful to refer back to what you've done and
+  explain afterwards.
+
+* :doc:`Topic guides </topics/index>` aim to explain a concept or subject at a
+  fairly high level.
+
+  Link to reference material rather than repeat it. Use examples and don't be
+  reluctant to explain things that seem very basic to you - it might be the
+  explanation someone else needs.
+
+  Providing background context helps a newcomer connect the topic to things
+  that they already know.
+
+* :doc:`Reference guides </ref/index>` contain technical reference for APIs.
+  They describe the functioning of Django's internal machinery and instruct in
+  its use.
+
+  Keep reference material tightly focused on the subject. Assume that the
+  reader already understands the basic concepts involved but needs to know or
+  be reminded of how Django does it.
+
+  Reference guides aren't the place for general explanation. If you find
+  yourself explaining basic concepts, you may want to move that material to a
+  topic guide.
+
+* :doc:`How-to guides </howto/index>` are recipes that take the reader through
+  steps in key subjects.
+
+  What matters most in a how-to guide is what a user wants to achieve.
+  A how-to should always be result-oriented rather than focused on internal
+  details of how Django implements whatever is being discussed.
+
+  These guides are more advanced than tutorials and assume some knowledge about
+  how Django works. Assume that the reader has followed the tutorials and don't
+  hesitate to refer the reader back to the appropriate tutorial rather than
+  repeat the same material.
+
 Writing style
 -------------