Code

Opened 7 years ago

Closed 7 years ago

#5195 closed (fixed)

Add multiple glaring warnings about doing SVN tutorial with Django 0.96

Reported by: ubernostrum Owned by: jacob
Component: Documentation Version: master
Severity: Keywords:
Cc: Triage Stage: Design decision needed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: UI/UX:

Description

We've had at least five tickets opened by people who downloaded Django 0.96 and then tried to work through the SVN version of the tutorial, which caused 0.96 to blow up on the keyword argument max_length. Similarly, people pop up on IRC and complain that adding a __unicode__ method to their models has no effect.

Adding admonitions to the appropriate places would hopefully help with this.

Attachments (1)

tutorial01.diff (2.3 KB) - added by ubernostrum 7 years ago.
Tutorial adding admonitions about using old Django with SVN tutorial

Download all attachments as: .zip

Change History (11)

Changed 7 years ago by ubernostrum

Tutorial adding admonitions about using old Django with SVN tutorial

comment:1 Changed 7 years ago by http://daniel.hahler.de/

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

Please replace "of of" with "of" (2 times).

comment:2 Changed 7 years ago by dAniel hAhler <django-bugs@…>

  • Has patch set
  • Patch needs improvement set

comment:3 Changed 7 years ago by SmileyChris

  • Triage Stage changed from Unreviewed to Design decision needed

comment:4 Changed 7 years ago by gwilson

Or maybe it's time we just release a new version?

comment:5 Changed 7 years ago by ubernostrum

New version's not ready, so constructive suggestions that don't involve a release would be welcome ;)

comment:6 Changed 7 years ago by Simon G. <dev@…>

This is a generic docs issue & not just the tutorials (although this is probably where people first encounter it) - there are plenty of tickets here that have been opened because people use the 0.97-pre docs instead of the one for their version. I would suggest that the best way to solve this would be to tweak the short notice on each doc page to point out that the user should choose the appropriate docs version to use. e.g.:

The current version of the docs has this prepended to each doc page on the site:

 This document is for Django's SVN release, which can be significantly different than previous releases. Get old docs here: 0.96, 0.95.

& change it to something like:

 This document is for Django's SVN release, which can be significantly different than previous releases. Please make sure to use the documentation version that matches the version of Django you are using. The docs for older versions are here: 0.96, 0.95.

Another idea would be to mention this in the obtaining/installing django pages.

comment:7 Changed 7 years ago by gwilson

This might just be one of those cases where no matter how many warnings we put up, it's not going to help the fact that people don't read.

We could maybe force people to choose a version, by having /documentation/ just be a listing of the different versions of documentation, something like http://www.postgresql.org/docs/.

Or what about making the latest released version be the default for showing at /documentation/. People using an SVN checkout would probably have less problems knowing where the correct documentation is.

comment:8 Changed 7 years ago by Simon G. <dev@…>

Here's another example: #5201, #5205 (clean_data should be cleaned_data).

comment:9 Changed 7 years ago by Simon G. <dev@…>

Sorry, that should be #5205, #5021, and #4927

comment:10 Changed 7 years ago by adrian

  • Resolution set to fixed
  • Status changed from new to closed

(In [6006]) Fixed #5195 -- Added notes to docs/tutorial01.txt about max_length and unicode() changes and 0.96 vs. development version. Thanks, ubernostrum

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.