Code

Opened 8 months ago

Closed 6 months ago

Last modified 6 months ago

#20910 closed Cleanup/optimization (fixed)

Specify the filename (when appropriate) with code snippets

Reported by: jggramlich@… Owned by: nsmgr8
Component: Documentation Version: 1.5
Severity: Normal Keywords: tutorial, afraid-to-commit
Cc: EvilDMP Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: no UI/UX: no

Description

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.

Attachments (0)

Change History (19)

comment:1 Changed 8 months ago by timo

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to needsinfo
  • Status changed from new to closed

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.

comment:2 Changed 8 months ago by anonymous

  • Resolution needsinfo deleted
  • Status changed from closed to new

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

comment:3 Changed 8 months ago by timo

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.

comment:4 follow-up: Changed 8 months ago by 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.

comment:5 Changed 8 months ago by mjtamlyn

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/

comment:6 Changed 8 months ago by 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.

comment:7 Changed 8 months ago by mjtamlyn

  • Keywords tutorial added
  • Type changed from Uncategorized to Cleanup/optimization

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.

comment:8 Changed 8 months ago by mjtamlyn

  • Summary changed from Documentation incomplete or misleading(?) to Specify the filename (when appropriate) with code snippets
  • Triage Stage changed from Unreviewed to Accepted

comment:9 Changed 8 months ago by anonymous

  • Summary changed from Specify the filename (when appropriate) with code snippets to Documentation incomplete or misleading(?)
  • Triage Stage changed from Accepted to Unreviewed

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.

comment:10 Changed 8 months ago by timo

  • Summary changed from Documentation incomplete or misleading(?) to Specify the filename (when appropriate) with code snippets
  • Triage Stage changed from Unreviewed to Accepted

Sounds great to me!

comment:11 in reply to: ↑ 4 Changed 7 months ago by EvilDMP

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.

comment:12 Changed 7 months ago by EvilDMP

  • Cc EvilDMP added
  • Keywords tutorial, afraid-to-commit added; tutorial removed

comment:13 Changed 7 months ago by anonymous

  • Owner changed from nobody to anonymous
  • Status changed from new to assigned

comment:14 Changed 7 months ago by nsmgr8

  • Owner changed from anonymous to nsmgr8

comment:15 Changed 7 months ago by nsmgr8

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

comment:16 Changed 7 months ago by timo

  • Has patch set

comment:17 Changed 7 months ago by timo

  • Patch needs improvement set

Comments for improvement on PR.

comment:18 Changed 6 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

In d07d6ae1167f93f2e88b3743c070003a66a31b35:

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

Thanks Marc Tamlyn for the suggestion.

comment:19 Changed 6 months ago by Tim Graham <timograham@…>

In 1be21651988374fc5b9b3cf8eb9afb76de229ff0/djangoproject.com:

Added CSS for sphinx snippet directive.

refs #20910.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.