Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added docs/documentation.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3560 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 49c67053db9e8ff3d3de4f51b8bb7ce0949ad0b7 1 parent a8705ce
Adrian Holovaty authored August 11, 2006

Showing 1 changed file with 140 additions and 0 deletions. Show diff stats Hide diff stats

  1. 140  docs/documentation.txt
140  docs/documentation.txt
... ...
@@ -0,0 +1,140 @@
  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 every 15 minutes. That
  46
+means they reflect the "latest and greatest" in Django -- they include the very
  47
+latest 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
+A key advantage of the Web-based documentation is the comment section at the
  52
+bottom of each document. This is an area for anybody to submit changes,
  53
+corrections and suggestions about the given document. The Django developers
  54
+frequently monitor the comments there and use them to improve the documentation
  55
+for everybody.
  56
+
  57
+We encourage you to help improve the docs: it's easy! Note, however, that
  58
+comments should explicitly relate to the documentation, rather than asking
  59
+broad tech-support questions. If you need help with your particular Django
  60
+setup, try the `django-users mailing list`_ instead of posting a comment to the
  61
+documentation.
  62
+
  63
+.. _django-users mailing list: http://groups.google.com/group/django-users
  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're interested, the script that
  98
+converts the ReST text docs into djangoproject.com's HTML lives at
  99
+`djangoproject.com/django_website/apps/docs/parts/build_documentation.py`_ in
  100
+the Django Subversion repository.
  101
+
  102
+.. _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
  103
+
  104
+Differences between versions
  105
+============================
  106
+
  107
+As previously mentioned, the text documentation in our Subversion repository
  108
+contains the "latest and greatest" changes and additions. These changes often
  109
+include documentation of new features added in the Django development version
  110
+-- the Subversion ("trunk") version of Django. For that reason, it's worth
  111
+pointing out our policy on keeping straight the documentation for various
  112
+versions of the framework.
  113
+
  114
+We follow this policy:
  115
+
  116
+    * The primary documentation on djangoproject.com is an HTML version of the
  117
+      latest docs in Subversion. These docs always correspond to the latest
  118
+      official Django release, plus whatever features we've added/changed in
  119
+      the framework *since* the latest release.
  120
+
  121
+    * As we add features to Django's development version, we try to update the
  122
+      documentation in the same Subversion commit transaction.
  123
+
  124
+    * To distinguish feature changes/additions in the docs, we use the phrase
  125
+      **New in Django development version**. In practice, this means that the
  126
+      current documentation on djangoproject.com can be used by users of either
  127
+      the latest release *or* the development version.
  128
+
  129
+    * Documentation for a particular Django release is frozen once the version
  130
+      has been released officially. It remains a snapshot of the docs as of the
  131
+      moment of the release. We will make exceptions to this rule in
  132
+      the case of retroactive security updates or other such retroactive
  133
+      changes. Once documentation is frozen, we add a note to the top of each
  134
+      frozen document that says "These docs are frozen for Django version XXX"
  135
+      and links to the current version of that document.
  136
+
  137
+    * The `main documentation Web page`_ includes links to documentation for
  138
+      all previous versions.
  139
+
  140
+.. _main documentation Web page: http://www.djangoproject.com/documentation/

0 notes on commit 49c6705

Please sign in to comment.
Something went wrong with that request. Please try again.