The problem we are discussing here is not really a django specific one. The concerns Adrian pointed out can be easily taken care of by using branches. In theory the generic documentation enhancement should be applicable to all releases, but we know its only really applicable to the previous release, or may be the one before that, so its not like we will have to maintain lost of branches either.
I say for each release, we create a branch, and each documentation enhancement be backported to it when applicable. I also say the default documentation on website be generated from the the latest release branch. This should solve all issues. On 8/26/07, James Bennett <[EMAIL PROTECTED]> wrote: > > > On 8/26/07, Nicola Larosa <[EMAIL PROTECTED]> wrote: > > Only if you make it so, and you shouldn't. :-) > > So do you have a means of pushing out updated docs to everyone who's > downloaded a tarball, every time we make a change that's not related > to documenting a change in Django itself? > > > It does not work. You cannot really get people to use the trunk docs, > but > > in many places say: "Oh, by the way, this little thing changed, please > > refer to the *right* release docs, but do come back when you're done, > thank > > you." again and again. > > Which isn't really what anyone's trying, so that's a bit of a red > herring. The problem we've been having is people who download the 0.96 > release and then try to follow the SVN version of the tutorial. This > simply will not work; there is no possibility of "do this part from > 0.96 and then come back", because the SVN tutorial is going to use > techniques (max_length instead of maxlength, __unicode__ instead of > __str__, named URL patterns, etc.) which simply cannot be made to work > on 0.96 in any fashion. > > Thus, the problem to solve here is simple: how do we ensure that > someone who downloads the 0.96 release uses the 0.96 version of the > documentation? > > Bundling HTML versions of the docs isn't a solution, because (speaking > from experience of reading django-users and hanging out on IRC) many > users never realize that the documentation is bundled with the > download in *any* format (just as many users probably never realize > that they get a free copy of "Dive Into Python" on most Debian-based > Linux distributions, and so ask where they can find a good Python > tutorial online). These are the same users who never find their way to > the release-specific docs on the website. > > Which is why it's been proposed that the default landing page for the > documentation should be the version for the latest release of Django, > not the SVN docs; this would solve the problem of people downloading > the release tarball (or installing a package on a Linux distro -- the > distros track releases, not SVN) and ending up at the SVN docs. > > > They shouldn't have to go the web site: the release docs should be on > their > > disk, within the installed release itself (see my other message). > > See above. I'm sure you mean well, but the experience of seeing people > actually work with Django and its documentation is against you on that > point. > > > -- > "Bureaucrat Conrad, you are technically correct -- the best kind of > correct." > > > > -- Amit Upadhyay Vakow! www.vakow.com +91-9820-295-512 --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com 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 -~----------~----~----~----~------~----~------~--~---
