diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/contributing.txt | 38 |
1 files changed, 38 insertions, 0 deletions
diff --git a/docs/contributing.txt b/docs/contributing.txt index f1ad0e3bb0..4ec5c3c2af 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -417,6 +417,44 @@ 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 ------------------------- |