Specify the filename (when appropriate) with code snippets

[jggramlich@…]

​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.

[Tim Graham]

You are welcome to provide a patch with any improvements. Without that however, I'm going to close this as I believe the tutorial strikes a good balance between being explicit in the beginning and then assuming the user will learn how Django works and not need hand-holding the entire time.

[anonymous]

...OR...you could leave the ticket open so somebody who deals with the documentation might see it on their todo list...as opposed to you just having a clean inbox.

The documentation says if you've got comments or issues about the documentation, open a ticket. Well, I've opened a ticket. If you're just going to delete anything five minutes after it's submitted because you don't "believe" it's valid...why bother in the first place?

[Tim Graham]

I'm sorry if I appeared dismissive and I appreciate the time you took to provide feedback. Consider, however, that complaining about "the whole tutorial" and throwing out statements like "This tutorial has been a major pain in my ass." is hurtful to the community of volunteers who have worked hard on it.

I've made hundreds of commits to the documentation and we currently have 110 open tickets, far from a "clean inbox". We welcome constructive feedback and patches!

Although it may be not perfect, I know that many people have successfully completed the tutorial as it is now. Many people have also provided feedback and patches which we have incorporated.

I will leave this open to let someone else weigh in on whether or not the tutorial could use some revision with respect to your comments, but I'm afraid no matter what we do, we won't be able to please everyone.

[jggramlich@…]

Fair enough. Your point about "...pain in my ass" is well taken.

What is the possibility of making the documentation into a wiki (I know this is not a small task) so that users can contribute easily? Is this being considered? You mentioned a "patch" earlier, which I can understand for code issues...but a patch...I don't know where to even begin for "patching" docs. I'd be more than happy to contribute (once I figure this stuff out).

If there is an process for patching docs, I'm all ears.

[Marc Tamlyn]

I think the big problem here is trying to provide a tutorial which is ideal for everyone is incredibly hard. To cover, say, an experienced developer in an alternative MVC technology (e.g. Rails, CakePHP etc) without being condescending, and to also cover a complete newbie developer is very challenging.

That said, some of your points are worth considering. It would be nice if the actual file was mentioned in a consistent way with each code snippet. The other comments personally I'm not so sure - it'd be verging on becoming over verbose.

I don't think the docs or the tutorial should be a wiki. It's harder to maintain quality and we don't have the resources to monitor for spamming.

As for contributing, you probably want to start here: ​https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/

[jggramlich@…]

I was thinking a well moderated wiki...but, not the point. Thanks for the link to the documentation writing. I'll do something with that and see about getting the changes I'd like to see done through that outlet.

You may close the ticket, and thank you.

[Marc Tamlyn]

I'm actually going to leave it open, but tidy it up to just reference the filenames. This is probably something which is not present because it's not built in rather than because it's not needed.

I think the best way of achieving this would perhaps be a custom sphinx directive (or adaptation of the existing code snippet one) to add the file name in a little bar across the top of the snippet. This could be applied in a number of other places around the "topics" documentation, for example in the CBV docs.

[anonymous]

That's almost exactly what I was thinking. Once I'm done with the tutorials and have my first app published, I'm going to download the sphinx, etc, and see about taking a crack at it.

[Tim Graham]

Sounds great to me!

[Daniele Procida]

Replying to jggramlich@…:

Fair enough. Your point about "...pain in my ass" is well taken.

What is the possibility of making the documentation into a wiki (I know this is not a small task) so that users can contribute easily? Is this being considered? You mentioned a "patch" earlier, which I can understand for code issues...but a patch...I don't know where to even begin for "patching" docs. I'd be more than happy to contribute (once I figure this stuff out).

If there is an process for patching docs, I'm all ears.

There is. And if you don't know where to start, start at ​http://dont-be-afraid-to-commit.readthedocs.org, which takes you through the entire process and includes a section on writing up documentation. I'm happy to help with that if you need it.

[M. Nasimul Haque]

I have made a new directive for prepending filename to the code snippet. All the code snippet in tutorial now includes the prepended filename.

Please review:
​https://github.com/django/django/pull/1672

[Tim Graham]

Comments for improvement on PR.

[Tim Graham <timograham@…>]

In d07d6ae1167f93f2e88b3743c070003a66a31b35:

Fixed #20910 -- Added a "snippet" sphinx directive to allow prefixing a filename.

Thanks Marc Tamlyn for the suggestion.

[Tim Graham <timograham@…>]

In 1be21651988374fc5b9b3cf8eb9afb76de229ff0/djangoproject.com:

Added CSS for sphinx snippet directive.

refs #20910.

[Tim Graham <timograham@…>]

In c49ea6f5:

Refs #20910 -- Replaced snippet directive with code-block.

[Tim Graham <timograham@…>]

In 1853e2db:

[2.1.x] Refs #20910 -- Replaced snippet directive with code-block.

Backport of c49ea6f5911296dcb40190c905e38b43cdc7c7a3 from master