Added 'How to document new features' to docs/contributing.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6083 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/contributing.txt b/docs/contributing.txt
index f1ad0e3bb0..4de31acc63 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -417,6 +417,46 @@ Documentation style
 We place a high importance on consistency and readability of documentation.
 (After all, Django was created in a journalism environment!)
 
+How to document new features
+----------------------------
+
+We treat our documentation like we treat our code: we aim to improve it as
+often as possible. This section explains how writers can craft their
+documentation changes in the most useful and least error-prone ways.
+
+Documentation changes come in two forms:
+
+    * General improvements -- Typo corrections, error fixes and better
+      explanations through clearer writing and more examples.
+
+    * New features -- Documentation of features that have been added to the
+      framework since the last release.
+
+Our philosophy is that "general improvements" are something that *all* current
+Django users should benefit from, including users of trunk *and* users of the
+latest release. Hence, the documentation section on djangoproject.com points
+people by default to the newest versions of the docs, because they have the
+latest and greatest content. (In fact, the Web site pulls directly from the
+Subversion repository, converting to HTML on the fly.)
+
+But this decision to feature bleeding-edge documentation has one large caveat:
+any documentation of *new* features will be seen by Django users who don't
+necessarily have access to those features yet, because they're only using the
+latest release. Thus, our policy is:
+
+    All documentation of new features should be written in a way that clearly
+    designates the features are only available in the Django development
+    version.
+
+    Assume documentation readers are using the latest release, not the
+    development version.
+
+Our traditional way of marking new features is by prefacing the features'
+documentation with: "New in Django development version." Changes aren't
+*required* to include this exact text, but all documentation of new features
+should include the phrase "development version," so we can find and remove
+those phrases for the next release.
+
 Guidelines for ReST files
 -------------------------