Now that 1.2 features have started to merge (great work everyone
involved with the Email backends and ManyToMany refactorings, they
look fantastic) we're entering one of those relatively rare periods of
instability in trunk. This is exactly the kind of time that we want
most of our regular users to be sticking with the 1.1.1 release, while
the super-engaged community members try out the new stuff as it's
added.
There's just one problem: http://docs.djangoproject.com/ defaults to
displaying the development docs. In fact, there isn't even an option
to see frozen docs for 1.1 (just an option to see them for 1.0). These
are going to start being pretty confusing for 1.1.1 users, for example
the e-mail docs now cover backends:
We include "New in Django Development version" warnings, but it still
feels a bit odd. In a post-1.0 world, I think it would make more sense
for the documentation linked to directly from the
docs.djangoproject.com homepage to cover the most recent official
release, with a bit less emphasis on the development version's docs.
Basically what the Python docs at http://docs.python.org/ do.
I may have missed a previous conversation about this, if so please
feel free to direct me to the old thread.
I definitely agree with this change. I've even had a hard time
finding 1.1 docs at all, it seems like the site dumps you to dev docs
by default, and if you look for "old" docs, you end up with 1.0 rather
than 1.1.
On Wed, Nov 4, 2009 at 5:47 PM, Simon Willison <si...@simonwillison.net> wrote:
> Now that 1.2 features have started to merge (great work everyone
> involved with the Email backends and ManyToMany refactorings, they
> look fantastic) we're entering one of those relatively rare periods of
> instability in trunk. This is exactly the kind of time that we want
> most of our regular users to be sticking with the 1.1.1 release, while
> the super-engaged community members try out the new stuff as it's
> added.
> There's just one problem: http://docs.djangoproject.com/ defaults to
> displaying the development docs. In fact, there isn't even an option
> to see frozen docs for 1.1 (just an option to see them for 1.0). These
> are going to start being pretty confusing for 1.1.1 users, for example
> the e-mail docs now cover backends:
> We include "New in Django Development version" warnings, but it still
> feels a bit odd. In a post-1.0 world, I think it would make more sense
> for the documentation linked to directly from the
> docs.djangoproject.com homepage to cover the most recent official
> release, with a bit less emphasis on the development version's docs.
> Basically what the Python docs at http://docs.python.org/ do.
> I may have missed a previous conversation about this, if so please
> feel free to direct me to the old thread.
On a related note, the Google Custom Search widget on the
documentation pages should ideally be updated to allow you to
explicitly search the 1.1 docs. Going forward, this should perhaps be
altered to remove the radio options and simply search through the
version of the docs you're currently viewing.
An additional 1.1 label/annotation will need to be configured in the
admin interface for the Google Custom Search. Jacob installed this
originally (as per my ticket #8723), so I guess he has the appropriate
Google Account login details.
Cheers,
Fraser
On Nov 4, 10:47 pm, Simon Willison <si...@simonwillison.net> wrote:
> Now that 1.2 features have started to merge (great work everyone
> involved with the Email backends and ManyToMany refactorings, they
> look fantastic) we're entering one of those relatively rare periods of
> instability in trunk. This is exactly the kind of time that we want
> most of our regular users to be sticking with the 1.1.1 release, while
> the super-engaged community members try out the new stuff as it's
> added.
> There's just one problem:http://docs.djangoproject.com/defaults to
> displaying the development docs. In fact, there isn't even an option
> to see frozen docs for 1.1 (just an option to see them for 1.0). These
> are going to start being pretty confusing for 1.1.1 users, for example
> the e-mail docs now cover backends:
> We include "New in Django Development version" warnings, but it still
> feels a bit odd. In a post-1.0 world, I think it would make more sense
> for the documentation linked to directly from the
> docs.djangoproject.com homepage to cover the most recent official
> release, with a bit less emphasis on the development version's docs.
> Basically what the Python docs athttp://docs.python.org/do.
> I may have missed a previous conversation about this, if so please
> feel free to direct me to the old thread.
> I definitely agree with this change. I've even had a hard time > finding 1.1 docs at all, it seems like the site dumps you to dev docs > by default, and if you look for "old" docs, you end up with 1.0 rather > than 1.1.
The 1.1 docs are there - at the somewhat predictable URL:
However, they aren't linked anywhere obvious that I can find, and they aren't explicitly available on the Google search widget.
I agree with Simon, though. Now that we have a semi-regular release schedule, there isn't as great a need to stay on trunk, so we should be encouraging people to download the stable release unless they have a need to ride the bleeding edge. To that end, the default docs should be stable, not development.
My only caveat on this is that we need to ensure 1.1 means "the current code in the 1.1.X branch", not "the contents of the 1.1 release". We are constantly updating and clarifying docs, and it's important that these changes are reflected online.
|
