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
20910	Specify the filename (when appropriate) with code snippets	jggramlich@…	M. Nasimul Haque	"https://docs.djangoproject.com/en/1.5/intro/tutorial03/

I make this complaint for the whole tutorial and not just this particular page or instance.  The specification of where particular bits of code is missing in many places, this is just one example.  Starting with:

***************copy from docs*****************

Raising a 404 error¶
Now, let’s tackle the poll detail view – the page that displays the question for a given poll. Here’s the view:

from django.http import Http404
# ...
def detail(request, poll_id):
    try:
        poll = Poll.objects.get(pk=poll_id)
    except Poll.DoesNotExist:
        raise Http404
    return render(request, 'polls/detail.html', {'poll': poll})
The new concept here: The view raises the Http404 exception if a poll with the requested ID doesn’t exist.

We’ll discuss what you could put in that polls/detail.html template a bit later, but if you’d like to quickly get the above example working, a file containing just:

{{ poll }}
will get you started for now.

*************/copy from docs*******************

I've got several problems with just this one cut/paste:

This code snippet is meant to be put....where?  I think whoever wrote this *assumes* that the tutorial reader knows or remembers exactly where this code snippet should go...it is not written in the documentation.  There are *several* code snippets that are just thrown into the tutorial, the writer assuming that the reader will know where this code is meant to go.  

The second bit about ""{{ poll }}"" is also vague.  There is more than one ""polls"" folders in my tree at this point.  Is it just ../mysite/polls/ or is it supposed to be in ../mysite/polls/templates/polls/?

Also about the ""{{ poll }}"" bit...the file this is meant to be written into is not specified.  I *think* it's meant to be put into polls/detail.html (again, don't really know where that's supposed to live)...but instead of coming out and saying ""put the code exactly here"" your documentation says ""...a file containing just: <code> will get you started for now.""  This is a completely vague and ambiguous statement.  Whoever wrote this makes way too many assumptions about what the reader should know. 

I've run into several roadblocks on this tutorial because of these assumptions.  I have to go back in the tutorial and re-read sections, sometimes guessing where code needs to be changed or inserted.  I'd have probably finished this tutorial and been on to the next one...and had a better idea of how the system is constructed...if the tutorial didn't make me guess and re-check everything.

Every time a code snippet is posted in the tutorial, you should make expressly clear:

- which file the code belongs in
- what code, if any, the new snippet is replacing
- what the files and directory structures look like (at that particular point in the tutorial)

Someone who knows django will probably know all this by heart and reflex, but a user like myself, just introduced to the platform and with no humans with experience on hand to direct me, does not know this.  This tutorial has been a major pain in my ass.
"	Cleanup/optimization	closed	Documentation	1.5	Normal	fixed	tutorial, afraid-to-commit	Daniele Procida	Accepted	1	0	0	1	0	0