id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
20184	Tutorial Instructions Don't Work	anonymous	nobody	"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)."	Uncategorized	closed	Documentation	1.5	Normal	needsinfo			Unreviewed	0	0	0	0	0	0