From f892464d58c4029e71f4ee0b4df08a724004d4eb Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 11 Sep 2007 11:46:34 +0000 Subject: newforms-admin: Merged to [6094] git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@6095 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/contributing.txt | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs') 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 ------------------------- -- cgit v1.3