Should docs.djangoproject.com link to 1.1 frozen docs by default, not SVN dev docs?

[Simon Willison-2]

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:

http://docs.djangoproject.com/en/dev/topics/email/

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.

Cheers,

Simon
--~--~---------~--~----~------------~-------~--~----~
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@...
To unsubscribe from this group, send email to django-developers+unsubscribe@...
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en
-~----------~----~----~----~------~----~------~--~---

[Taylor Marshall]

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.

-taylor

On Wed, Nov 4, 2009 at 5:47 PM, Simon Willison <simon@...> 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:
>
> http://docs.djangoproject.com/en/dev/topics/email/
>
> 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.
>
> Cheers,
>
> Simon
> >
>

--~--~---------~--~----~------------~-------~--~----~
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@...
To unsubscribe from this group, send email to django-developers+unsubscribe@...
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en
-~----------~----~----~----~------~----~------~--~---

[Fraser Nevett]

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...@...> 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:
>
> http://docs.djangoproject.com/en/dev/topics/email/
>
> 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.
>
> Cheers,
>
> Simon

--~--~---------~--~----~------------~-------~--~----~
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@...
To unsubscribe from this group, send email to django-developers+unsubscribe@...
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en
-~----------~----~----~----~------~----~------~--~---

[Russell Keith-Magee-2]

On Thu, Nov 5, 2009 at 8:48 AM, Taylor Marshall
<taylor.paul.marshall@...> wrote:
>
> 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:

http://docs.djangoproject.com/en/1.1/

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.

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 django-developers@...
To unsubscribe from this group, send email to django-developers+unsubscribe@...
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en
-~----------~----~----~----~------~----~------~--~---

[SmileyChris]

This should be a high priority fix.

Anyone new to Django and using the installation of 1.1.1 (which the
download page recommends over trunk) will currently be unable to
follow the tutorial.
I was having a face to face meeting today with someone who had exactly
this problem.

On Nov 6, 1:53 am, Russell Keith-Magee <freakboy3...@...> wrote:

> On Thu, Nov 5, 2009 at 8:48 AM, Taylor Marshall
>
> <taylor.paul.marsh...@...> wrote:
>
> > 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:
>
> http://docs.djangoproject.com/en/1.1/
>
> 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.
>
> 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 django-developers@....
To unsubscribe from this group, send email to django-developers+unsubscribe@....
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.