--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/intro/whatsnext.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,231 @@
+=================
+What to read next
+=================
+
+So you've read all the :doc:`introductory material </intro/index>` and have
+decided you'd like to keep using Django. We've only just scratched the surface
+with this intro (in fact, if you've read every single word you've still read
+less than 10% of the overall documentation).
+
+So what's next?
+
+Well, we've always been big fans of learning by doing. At this point you should
+know enough to start a project of your own and start fooling around. As you need
+to learn new tricks, come back to the documentation.
+
+We've put a lot of effort into making Django's documentation useful, easy to
+read and as complete as possible. The rest of this document explains more about
+how the documentation works so that you can get the most out of it.
+
+(Yes, this is documentation about documentation. Rest assured we have no plans
+to write a document about how to read the document about documentation.)
+
+Finding documentation
+=====================
+
+Django's got a *lot* of documentation -- almost 200,000 words -- so finding what
+you need can sometimes be tricky. A few good places to start are the :ref:`search`
+and the :ref:`genindex`.
+
+Or you can just browse around!
+
+How the documentation is organized
+==================================
+
+Django's main documentation is broken up into "chunks" designed to fill
+different needs:
+
+ * The :doc:`introductory material </intro/index>` is designed for people new
+ to Django -- or to Web development in general. It doesn't cover anything
+ in depth, but instead gives a high-level overview of how developing in
+ Django "feels".
+
+ * The :doc:`topic guides </topics/index>`, on the other hand, dive deep into
+ individual parts of Django. There are complete guides to Django's
+ :doc:`model system </topics/db/index>`, :doc:`template engine
+ </topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much
+ more.
+
+ This is probably where you'll want to spend most of your time; if you work
+ your way through these guides you should come out knowing pretty much
+ everything there is to know about Django.
+
+ * Web development is often broad, not deep -- problems span many domains.
+ We've written a set of :doc:`how-to guides </howto/index>` that answer
+ common "How do I ...?" questions. Here you'll find information about
+ :doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing
+ custom template tags </howto/custom-template-tags>`, and more.
+
+ Answers to really common questions can also be found in the :doc:`FAQ
+ </faq/index>`.
+
+ * The guides and how-to's don't cover every single class, function, and
+ method available in Django -- that would be overwhelming when you're
+ trying to learn. Instead, details about individual classes, functions,
+ methods, and modules are kept in the :doc:`reference </ref/index>`. This is
+ where you'll turn to find the details of a particular function or
+ whathaveyou.
+
+ * Finally, there's some "specialized" documentation not usually relevant to
+ most developers. This includes the :doc:`release notes </releases/index>`,
+ :doc:`documentation of obsolete features </obsolete/index>`,
+ :doc:`internals documentation </internals/index>` for those who want to add
+ code to Django itself, and a :doc:`few other things that simply don't fit
+ elsewhere </misc/index>`.
+
+
+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 online is a separate text file in the repository.
+
+.. _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://docs.djangoproject.com/en/dev/. These HTML pages are generated
+automatically from the text files in source control. 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.)
+
+We encourage you to help improve the docs by submitting changes, corrections and
+suggestions in the `ticket system`_. The Django developers actively monitor the
+ticket system and use your feedback to improve the documentation for everybody.
+
+Note, however, that tickets 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`_ or the `#django
+IRC channel`_ instead.
+
+.. _ticket system: http://code.djangoproject.com/simpleticket?component=Documentation
+.. _django-users mailing list: http://groups.google.com/group/django-users
+.. _#django IRC channel: irc://irc.freenode.net/django
+
+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:
+
+.. code-block:: bash
+
+ $ 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 "max_length" in any
+Django document:
+
+.. code-block:: bash
+
+ $ grep -r max_length /path/to/django/docs/
+
+As HTML, locally
+----------------
+
+You can get a local copy of the HTML documentation following a few easy steps:
+
+ * Django's documentation uses a system called Sphinx__ to convert from
+ plain text to HTML. You'll need to install Sphinx by either downloading
+ and installing the package from the Sphinx Web site, or by Python's
+ ``easy_install``:
+
+ .. code-block:: bash
+
+ $ easy_install Sphinx
+
+ * Then, just use the included ``Makefile`` to turn the documentation into
+ HTML:
+
+ .. code-block:: bash
+
+ $ cd path/to/django/docs
+ $ make html
+
+ You'll need `GNU Make`__ installed for this.
+
+ * The HTML documentation will be placed in ``docs/_build/html``.
+
+.. note::
+
+ Generation of the Django documentation will work with Sphinx version 0.6
+ or newer, but we recommend going straight to Sphinx 1.0.2 or newer.
+
+__ http://sphinx.pocoo.org/
+__ http://www.gnu.org/software/make/
+
+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 version X.Y", being X.Y the next release version (hence, the one
+ being developed).
+
+ * 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.
+
+ * The `main documentation Web page`_ includes links to documentation for
+ all previous versions.
+
+.. _main documentation Web page: http://docs.djangoproject.com/en/dev/