Changeset 6083

Timestamp:

09/09/07 22:42:33 (1 year ago)

Author:

adrian

Message:

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

Files:

• django/trunk/docs/contributing.txt (modified) (1 diff)

django/trunk/docs/contributing.txt

@@ -417 +417 @@
-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