Django first example needs minor but significant improvement?

[Kilgore Sixsixone]

I've just started learning Django from the Polls example which did not work for me after 30 minutes of really - and I mean really - checking that I had done exactly what I was told to do. I eventually found (i) I was not the first person to have exactly this problem and (ii) the cause is insufficiently clear instructions.

I would like to suggest that the documentation is improved along the lines set out below (assuming I am correct of course). How do I bring this matter to the attention of the people responsible?

For those interested, here's the issue:

The tutorial says

The next step is to point the root URLconf at the polls.urls module. In mysite/urls.py


I content this is incorrect or misleading. It should imo say

The next step is to point the root URLconf at the polls.urls module. In mysite/mysite/urls.py


One could argue that the former is correct but given that (a) this introductory/hand-holding material, (b) there are three files called urls.py in scope all with very similar contents and (c) more than one person has misunderstood the instruction, I think the latter is better.

A second issue is the instruction:

Let’s write the first view. Open the file polls/views.py and put the following Python code in it:

The issue is that the file concerned has already been created by this stage so "put" is ambiguous. It could mean "add" or "replace the current contents" with. It happens that the code referred to is all about the necessary imports for URLconf-ing which is exactly the context of the problem in the first issue.

[Vijay Khemlani]

All the paths in that documentation are relative to the path of the project:

polls/views.py

polls/urls.py

etc

and at the beginning of the page it even shows the file tree

mysite/

    manage.py

    mysite/

        __init__.py

        settings.py

        urls.py

        wsgi.py

Also there are only two urls.py files, not three

For the views.py it explicitly says "Open the file polls/views.py", not create, that should be enough to imply that the file actually exists.

I'm not a native english speaker but I had no trouble following the tutorial, but you need to read the documentation with care.

--
You received this message because you are subscribed to the Google Groups "Django users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to django-users+unsubscribe@googlegroups.com.
To post to this group, send email to django...@googlegroups.com.
Visit this group at https://groups.google.com/group/django-users.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-users/31f6b09f-ef93-42d6-ad3b-e187761072e0%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.