Tutorial Instructions Don't Work

[anonymous]

There were a number of issues encountered while trying to install Django:

1. The web site should show a link to the zip file prior to a link to the tar.gz file. In fact, you can get rid of the .tar.gz file because they don't work on Windows; whereas, a .zip file works on both Unix and Windows without extra software.

2. Steps within instructions should be enumerated: (1) Do this. (2) Do this. (3) Do this. When you do not enumerate steps, it is easy to miss a step. In other words, don't use paragraph form for steps.

3. The line "django-admin.py startproject mysite" doesn't work. At this point in the instructions we both know that it isn't going to work because there are no instructions to indicate the proper working directory. So instead of hiding this fact behind another web page (Problems running...), add it as another step.

4. There should be only a single download to install Django. It can be very confusing to new users to have to (1) install django, but before installing django, you have to (2) install pip, but before installing pip you have to (3) install etc. Not streamlined at all. Instead, split the instructions between a "quick" and "advanced". The "advanced" pages can talk about pip and that other program. Someone who first sees Django, and possibly Python for the first time, will have no idea about Pip and the other program. Simplify, simplify, simplify.

5. The instructions for editing polls/model.py should read:

1) Edit polls/model.py.
2) Replace the contents with:

... insert the code here ...

3) Save the file. <- This needs to be explicitly stated.

Most importantly, have a technical writer try to follow the instructions. This is called vetting. Not only do you have to test your software, but you also have to test the documentation created for the project.

Just like in business where you want to make it as easy as possible for people to give you money, you want to make installation as easy and painless (for newbies) as possible. Simplify (e.g., .tar.gz format is not cross-platform, but Python is, so don't use it: simplify).

[Aymeric Augustin]

Given the number of people who have successfully followed the tutorial on Windows, OS X, and Linux, I don't think the title is entirely accurate.

Generally speaking, you seem to assume that those who wrote the docs didn't think about any of this. I don't claim the docs are perfect, but there the result of several debates on these topics, and they're a compromise taking into account more problems that those you've considered.

Please review the past discussions on these topics, make concrete proposals addressing the arguments raised in these discussions. Then we can consider changing things.

---

Here's a quick breakdown of my feedback.

1. wontfix — tar.gz is the standard format for distributing open-source software. If having a .tar.gz and a .zip discourages someone from using Django, I'm fine not having to support that person in this tracker and on the mailing lists.
2. ddn — I'm not convinced that would make the docs more readable, but why not; I'll defer to a docs maintainer.
3. needsinfo — we've revised this half a dozen time to cater for the problems in various versions of Windows. See general remark above.
4. wontfix — you will always have to at least a) purchase a computer b) purchase or download an operating system c) download a text editor or an IDE d) download Python e) download Django. It's possible to install Django without pip, but then upgrading is very problematic. Therefore, we've added an extra step, install pip. Again, see general remark above.
5. wontfix — are you kidding? Same comment as for 1.

Sorry for being blunt, but the documentation are written for developers with a brain, not for button-pushers. I'm not against having a technical writer proof-read them if you'd like to sponsor such work, but I'm against dumbing them down.

For instance, I'm strongly against making them MSDN-style: extensive docs that are perfectly correct, perfectly regular in style, but never tell you anything you couldn't guess from the signature of the objects, nor tell you why you should or shouldn't use something.

To sum up, you won't get any argument from me that simplicity is important, but this must be balanced with the variety of people using Django, and our limited resources (we don't want to maintain a tutorial for Windows and a tutorial for Unix).

[Tim Graham]

If the reporter would like to provide a patch to address any of the issues, I would be happy to review it, but absent that, I don't see anything particularly actionable here.