Opened 12 years ago

Closed 12 years ago

Last modified 12 years ago

#18725 closed Cleanup/optimization (worksforme)

Django tutorial should give stronger warning about uninstalling

Reported by: anonymous Owned by: nobody
Component: Documentation Version: 1.4
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: yes
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

Installation of new version of Django while old version is not deleted causes various problems and this is not described in documentation. You should mention this in the very beginning of the tutorial for beginners or make the installation without such problems.

Change History (9)

comment:1 by Aymeric Augustin, 12 years ago

Resolution: worksforme
Status: newclosed

This is documented here and there.

comment:2 by anonymous, 12 years ago

But in tutorial https://docs.djangoproject.com/en/dev/intro/tutorial01/
is only this text: "See How to install Django for advice on how to remove older versions of Django and install a newer one.". What if people want to skip installation guide as obvious? Very many do so, as can be seen from problems on django-related forums. And after several hours of frustration each solves problem themselves: "Oh, i forgot to delete old version". Something wrong here, and the problem is in the docs.

comment:3 by anonymous, 12 years ago

"worksforme". It's laughable :)) . Program should work for your users. Sorry.

comment:4 by Russell Keith-Magee, 12 years ago

Component: UncategorizedDocumentation
Easy pickings: set
Needs documentation: set
Resolution: worksforme
Status: closedreopened
Summary: Django incorrectly updatesDjango tutorial should give stronger warning about uninstalling
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

Given the importance of uninstalling older versions before installing new ones, it's probably worth beefing up the note in the tutorial about installation so that it's *very* clear that you have to remove older versions, or hilarity will ensue.

comment:5 by Aymeric Augustin, 12 years ago

We have to chose what we put at the very beginning of the tutorial, and balance the importance of the different pieces of information. In my opinion, the priorities are:

  • 1) things absolute beginners need to know
  • 2) common pitfalls

Since our docs no longer recommend python setup.py install, you can only encounter this particular problem if you've installed Django at least once in the past — so you aren't a beginner — and if you haven't followed the installation docs in the first place. (By the way this problem may affect all libraries installed in this way, it isn't specific to Django.)

For these reasons, the existing sentence seems sufficient to me. There are dozens of other pitfalls that you can encounter in the tutorial. This one is already mentioned extremely clearly at the very beginning, giving it a very high relative importance. The tutorial 1 already has more "important notes" than text; we can't turn everything into an important note.

At some point, we can't do much for users who don't read the docs (neither the installation instructions nor the advice to uninstall previous versions) and then proceed to make ironic comments here!

comment:6 by James Bennett, 12 years ago

Russ, I do think this is a case where there are limits to how much we can reasonably do at the start of the tutorial. Especially given that you can only run into this if A) you've installed Django before and B) you ignore the instructions we provide, I'm OK with leaving as-is.

comment:7 by nickmartini, 12 years ago

I revisited the documentation in question and I saw that immediately before the mentioned link it reads: "Check also that the version number matches the version of this tutorial. If they don't match, you can refer to the tutorial for your version of Django or update Django to the newest version." In order for someone to run into previous version conflicts, they would have to disregard the documentation in place. Furthermore, users only need to uninstall previous versions if they aren't using pip. I suggest we leave the documentation as-is.

Last edited 12 years ago by nickmartini (previous) (diff)

comment:8 by anonymous, 12 years ago

Resolution: worksforme
Status: reopenedclosed

If someone's ignoring the existing warnings about this, they're not going to pay attention to more/strongly-worded warnings either. Closing worksforme since the existing docs already tell you to be careful about this issue.

comment:9 by James Bennett, 12 years ago

Blah. Last comment was me, but I wasn't logged in.

Note: See TracTickets for help on using tickets.
Back to Top