+
−====================================
+
−How to read the Django documentation
+
−====================================
+
−
+
−We've put a lot of effort into making Django's documentation useful, easy to
+
−read and as complete as possible. Here are a few tips on how to make the best
+
−of it, along with some style guidelines.
+
−
+
−(Yes, this is documentation about documentation. Rest assured we have no plans
+
−to write a document about how to read the document about documentation.)
+
−
+
−How documentation is updated
+
−============================
+
−
+
−Just as the Django code base is developed and improved on a daily basis, our
+
−documentation is consistently improving. We improve documentation for several
+
−reasons:
+
−
+
−    * To make content fixes, such as grammar/typo corrections.
+
−    * To add information and/or examples to existing sections that need to be
+
−      expanded.
+
−    * To document Django features that aren't yet documented. (The list of
+
−      such features is shrinking but exists nonetheless.)
+
−    * To add documentation for new features as new features get added, or as
+
−      Django APIs or behaviors change.
+
−
+
−Django's documentation is kept in the same source control system as its code.
+
−It lives in the `django/trunk/docs`_ directory of our Subversion repository.
+
−Each document is a separate text file that covers a narrowly focused topic,
+
−such as the "generic views" framework or how to construct a database model.
+
−
+
−.. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs
+
−
+
−Where to get it
+
−===============
+
−
+
−You can read Django documentation in several ways. They are, in order of
+
−preference:
+
−
+
−On the Web
+
−----------
+
−
+
−The most recent version of the Django documentation lives at
+
−http://www.djangoproject.com/documentation/ . These HTML pages are generated
+
−automatically from the text files in source control every 15 minutes. That
+
−means they reflect the "latest and greatest" in Django -- they include the very
+
−latest corrections and additions, and they discuss the latest Django features,
+
−which may only be available to users of the Django development version. (See
+
−"Differences between versions" below.)
+
−
+
−A key advantage of the Web-based documentation is the comment section at the
+
−bottom of each document. This is an area for anybody to submit changes,
+
−corrections and suggestions about the given document. The Django developers
+
−frequently monitor the comments there and use them to improve the documentation
+
−for everybody.
+
−
+
−We encourage you to help improve the docs: it's easy! Note, however, that
+
−comments should explicitly relate to the documentation, rather than asking
+
−broad tech-support questions. If you need help with your particular Django
+
−setup, try the `django-users mailing list`_ instead of posting a comment to the
+
−documentation.
+
−
+
−.. _django-users mailing list: http://groups.google.com/group/django-users
+
−
+
−In plain text
+
−-------------
+
−
+
−For offline reading, or just for convenience, you can read the Django
+
−documentation in plain text.
+
−
+
−If you're using an official release of Django, note that the zipped package
+
−(tarball) of the code includes a ``docs/`` directory, which contains all the
+
−documentation for that release.
+
−
+
−If you're using the development version of Django (aka the Subversion "trunk"),
+
−note that the ``docs/`` directory contains all of the documentation. You can
+
−``svn update`` it, just as you ``svn update`` the Python code, in order to get
+
−the latest changes.
+
−
+
−You can check out the latest Django documentation from Subversion using this
+
−shell command::
+
−
+
−    svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs
+
−
+
−One low-tech way of taking advantage of the text documentation is by using the
+
−Unix ``grep`` utility to search for a phrase in all of the documentation. For
+
−example, this will show you each mention of the phrase "edit_inline" in any
+
−Django document::
+
−
+
−    grep edit_inline /path/to/django/docs/*.txt
+
−
+
−Formatting
+
−~~~~~~~~~~
+
−
+
−The text documentation is written in ReST (ReStructured Text) format. That
+
−means it's easy to read but is also formatted in a way that makes it easy to
+
−convert into other formats, such as HTML. If you're interested, the script that
+
−converts the ReST text docs into djangoproject.com's HTML lives at
+
−`djangoproject.com/django_website/apps/docs/parts/build_documentation.py`_ in
+
−the Django Subversion repository.
+
−
+
−.. _djangoproject.com/django_website/apps/docs/parts/build_documentation.py: http://code.djangoproject.com/browser/djangoproject.com/django_website/apps/docs/parts/build_documentation.py
+
−
+
−Differences between versions
+
−============================
+
−
+
−As previously mentioned, the text documentation in our Subversion repository
+
−contains the "latest and greatest" changes and additions. These changes often
+
−include documentation of new features added in the Django development version
+
−-- the Subversion ("trunk") version of Django. For that reason, it's worth
+
−pointing out our policy on keeping straight the documentation for various
+
−versions of the framework.
+
−
+
−We follow this policy:
+
−
+
−    * The primary documentation on djangoproject.com is an HTML version of the
+
−      latest docs in Subversion. These docs always correspond to the latest
+
−      official Django release, plus whatever features we've added/changed in
+
−      the framework *since* the latest release.
+
−
+
−    * As we add features to Django's development version, we try to update the
+
−      documentation in the same Subversion commit transaction.
+
−
+
−    * To distinguish feature changes/additions in the docs, we use the phrase
+
−      **New in Django development version**. In practice, this means that the
+
−      current documentation on djangoproject.com can be used by users of either
+
−      the latest release *or* the development version.
+
−
+
−    * Documentation for a particular Django release is frozen once the version
+
−      has been released officially. It remains a snapshot of the docs as of the
+
−      moment of the release. We will make exceptions to this rule in
+
−      the case of retroactive security updates or other such retroactive
+
−      changes. Once documentation is frozen, we add a note to the top of each
+
−      frozen document that says "These docs are frozen for Django version XXX"
+
−      and links to the current version of that document.
+
−
+
−    * Once a document is frozen for a Django release, we remove comments from
+
−      that page, in favor of having comments on the latest version of that
+
−      document. This is for the sake of maintainability and usability, so that
+
−      users have one, and only one, place to leave comments on a particular
+
−      document. We realize that some people may be stuck on a previous version
+
−      of Django, but we believe the usability problems with multiple versions
+
−      of a document the outweigh the benefits.
+
−
+
−    * The `main documentation Web page`_ includes links to documentation for
+
−      all previous versions.
+
−
+
−.. _main documentation Web page: http://www.djangoproject.com/documentation/