On Tue, Feb 16, 2010 at 3:28 PM, Andrew Badr <[email protected]> wrote: > What's the policy about all those references to release notes in the > docs? For example, the autoescape template tag [1] has "New in Django > 1.0: Please, see the release notes", with a link to the 1.0 release > notes. When can these be removed?
I don't think we have an existing policy for this -- mostly because it hasn't really been an issue until now. I agree that the release notes shouldn't be the place to document a feature. They really should only document what has changed, and/or any upgrading instructions that may be required. The full feature description should always be in the main documentation. I also agree that the versionadded tags should be pruned, though. Aside from the obvious problems like the bad links you reference, some parts of the docs have so many versionadded tags that it's hard to tell which versionadded tags apply to which text. My initial reaction is that we should preserve the version added/changed tags for actively supported releases - that is, the official 1.2 docs will contain the notes for what was added in 1.2 (the current release) 1.1 (the previous stable release). Once a release fades into the 'security updates only' phase, I don't think it's unreasonable to suggest that the documentation should move on as well. It's not like that documentation is lost, either. We have v1.0 documentation available on the website, so if you want to know if a particular feature was available in v1.0, it is possible to check. Yours, Russ Magee %-) -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
