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 ` 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 ` discuss key topics and concepts at a + fairly a fairly high level and provide useful background information and + explanation. + +* :doc:`Reference guides ` 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 ` 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 `. After that, you'll want to read about the :ref:`Sphinx-specific markup ` that's used to manage metadata, indexing, and cross-references. +How the documentation is organized +---------------------------------- + +The documentation is organized into several categories: + +* :doc:`Tutorials ` 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 ` 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 ` 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 ` 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 -------------