docs/documentation.txt

   1 ====================================
   2 How to read the Django documentation
   3 ====================================
   4
   5 We've put a lot of effort into making Django's documentation useful, easy to
   6 read and as complete as possible. Here are a few tips on how to make the best
   7 of it, along with some style guidelines.
   8
   9 (Yes, this is documentation about documentation. Rest assured we have no plans
  10 to write a document about how to read the document about documentation.)
  11
  12 How documentation is updated
  13 ============================
  14
  15 Just as the Django code base is developed and improved on a daily basis, our
  16 documentation is consistently improving. We improve documentation for several
  17 reasons:
  18
  19     * To make content fixes, such as grammar/typo corrections.
  20     * To add information and/or examples to existing sections that need to be
  21       expanded.
  22     * To document Django features that aren't yet documented. (The list of
  23       such features is shrinking but exists nonetheless.)
  24     * To add documentation for new features as new features get added, or as
  25       Django APIs or behaviors change.
  26
  27 Django's documentation is kept in the same source control system as its code.
  28 It lives in the `django/trunk/docs`_ directory of our Subversion repository.
  29 Each document is a separate text file that covers a narrowly focused topic,
  30 such as the "generic views" framework or how to construct a database model.
  31
  32 .. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs
  33
  34 Where to get it
  35 ===============
  36
  37 You can read Django documentation in several ways. They are, in order of
  38 preference:
  39
  40 On the Web
  41 ----------
  42
  43 The most recent version of the Django documentation lives at
  44 http://www.djangoproject.com/documentation/ . These HTML pages are generated
  45 automatically from the text files in source control. That means they reflect
  46 the "latest and greatest" in Django -- they include the very latest
  47 corrections and additions, and they discuss the latest Django features,
  48 which may only be available to users of the Django development version. (See
  49 "Differences between versions" below.)
  50
  51 We encourage you to help improve the docs by submitting changes, corrections
  52 and suggestions in the `ticket system`_. The Django developers actively monitor
  53 the ticket system and use your feedback to improve the documentation for
  54 everybody.
  55
  56 Note, however, that tickets should explicitly relate to the documentation,
  57 rather than asking broad tech-support questions. If you need help with your
  58 particular Django setup, try the `django-users mailing list`_ or the
  59 `#django IRC channel`_ instead.
  60
  61 .. _ticket system: http://code.djangoproject.com/simpleticket?component=Documentation
  62 .. _django-users mailing list: http://groups.google.com/group/django-users
  63 .. _#django IRC channel: irc://irc.freenode.net/django
  64
  65 In plain text
  66 -------------
  67
  68 For offline reading, or just for convenience, you can read the Django
  69 documentation in plain text.
  70
  71 If you're using an official release of Django, note that the zipped package
  72 (tarball) of the code includes a ``docs/`` directory, which contains all the
  73 documentation for that release.
  74
  75 If you're using the development version of Django (aka the Subversion "trunk"),
  76 note that the ``docs/`` directory contains all of the documentation. You can
  77 ``svn update`` it, just as you ``svn update`` the Python code, in order to get
  78 the latest changes.
  79
  80 You can check out the latest Django documentation from Subversion using this
  81 shell command::
  82
  83     svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs
  84
  85 One low-tech way of taking advantage of the text documentation is by using the
  86 Unix ``grep`` utility to search for a phrase in all of the documentation. For
  87 example, this will show you each mention of the phrase "edit_inline" in any
  88 Django document::
  89
  90     grep edit_inline /path/to/django/docs/*.txt
  91
  92 Formatting
  93 ~~~~~~~~~~
  94
  95 The text documentation is written in ReST (ReStructured Text) format. That
  96 means it's easy to read but is also formatted in a way that makes it easy to
  97 convert into other formats, such as HTML. If you have the `reStructuredText`_
  98 library installed, you can use ``rst2html`` to generate your own HTML files.
  99
 100 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 101
 102 Differences between versions
 103 ============================
 104
 105 As previously mentioned, the text documentation in our Subversion repository
 106 contains the "latest and greatest" changes and additions. These changes often
 107 include documentation of new features added in the Django development version
 108 -- the Subversion ("trunk") version of Django. For that reason, it's worth
 109 pointing out our policy on keeping straight the documentation for various
 110 versions of the framework.
 111
 112 We follow this policy:
 113
 114     * The primary documentation on djangoproject.com is an HTML version of the
 115       latest docs in Subversion. These docs always correspond to the latest
 116       official Django release, plus whatever features we've added/changed in
 117       the framework *since* the latest release.
 118
 119     * As we add features to Django's development version, we try to update the
 120       documentation in the same Subversion commit transaction.
 121
 122     * To distinguish feature changes/additions in the docs, we use the phrase
 123       **New in Django development version**. In practice, this means that the
 124       current documentation on djangoproject.com can be used by users of either
 125       the latest release *or* the development version.
 126
 127     * Documentation for a particular Django release is frozen once the version
 128       has been released officially. It remains a snapshot of the docs as of the
 129       moment of the release. We will make exceptions to this rule in
 130       the case of retroactive security updates or other such retroactive
 131       changes. Once documentation is frozen, we add a note to the top of each
 132       frozen document that says "These docs are frozen for Django version XXX"
 133       and links to the current version of that document.
 134
 135     * The `main documentation Web page`_ includes links to documentation for
 136       all previous versions.
 137
 138 .. _main documentation Web page: http://www.djangoproject.com/documentation/