From b82a44d2706a08ddf848960f8b777f47db66f376 Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Mon, 10 Sep 2007 03:42:33 +0000 Subject: [PATCH] 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 --- docs/contributing.txt | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) 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 -------------------------