Clarity

[chris.is.fun+django@…]

Three suggestions to make this clearer for us newbs.

First, when you refer to /django/contrib/ it would be good to give a few examples of where that might be, like for Ubuntu it's /var/python-support/python2.6/django/contrib/. That wasn't obvious to me.

Second, Use the template system was unclear in the following way.

<h1>{{ poll.question }}</h1>
<ul>
{% for choice in poll.choice_set.all %}
    <li>{{ choice.choice }}</li>
{% endfor %}
</ul>

it's unclear which "poll" is being referred to: the model Poll, the foreign key poll, or the poll that was passed from p through a dictionary in the view. (I think "view" is the place it was passed.)

Also it's confusing when you refer to a set as X and a member of the set as X. Maybe in the above you could do

{% for c in poll_fk.choice_set.all %}
{{c.choice}}
{% endfor%}

or maybe it's {{choice.c}} , I can't tell whether the set or the member comes first.

Finally choice_set is an infelicitous word because "choice set" could refer to the result of like a SQL query or many other sets of choices. Maybe in a newer version of the tutorial you could name the models differently. How about "polls" and "answers" ?

[Luke Plant]

First, regarding /django/contrib in tutorial part 2, there is no standard place that this stuff is put, and we don't want to get into adding information about where distributions put it - we cannot predict these things, and it can easily change. Users need to know how to use the system they are on to find out where files are put, I'm afraid.

For the second point, the text surrounding the example, as well as the view code that is referenced, make it clear that 'poll' is a poll object, i.e. an instance of Poll. It couldn't be anything else. It is standard practice in Python to give classes singular names, and objects the same name, but lower case, as the class they are an instance of. Shortening the name to a single character doesn't help.

You seem to be confused also in this point - {{ choice.choice }} refers to the choice attribute of the choice object. This is certainly a potential source of confusion, but I think it is pretty clear once you've gone through the first tutorial. The dot in between represents Python attribute lookup, not set/member or member/set, which should be obvious to anyone with minimal Python knowledge - and you can gain such minimal knowledge by following the first part of the tutorial.

Final point - I think 'choice_set' is clear once you've gone through the first tutorial, which encourages you to explore the API, and has lots of examples. I don't really understand the objection here, because your alternative is vulnerable to exactly the same objection - if it were 'answer_set' that could refer to the result of an SQL query or many other sets of answers. In this context, given the API that has been demonstrated in part 1, there really isn't anything else that 'choices_set' could be.