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

.. _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

===========

: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

-------------