Opened 6 years ago

Closed 5 years ago

Last modified 4 years ago

#12249 closed (wontfix)

csrf_token not clear in User Authentication docs

Reported by: drozzy Owned by: gabrielhurley
Component: Documentation Version: 1.1
Severity: Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

Someone please add an explanation as to why the {% csrf_token %} is present in the User Authentication docs example HTML template:
http://docs.djangoproject.com/en/dev/topics/auth/#django.contrib.auth.views.login

Right now it seems like "wth"? Where did that come from! Almost looks like an error.

Please include explanation of what the tags means (or at least link to the tag info page) and why it should be included in the template.

Attachments (1)

12249_docs_patch.diff (1.1 KB) - added by gabrielhurley 5 years ago.
Adds info on csrf_token ahead of the form in question.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 5 years ago by russellm

  • milestone set to 1.2
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

Changed 5 years ago by gabrielhurley

Adds info on csrf_token ahead of the form in question.

comment:2 Changed 5 years ago by gabrielhurley

  • Has patch set
  • Owner changed from nobody to gabrielhurley
  • Status changed from new to assigned
  • Summary changed from csrf_token not clear in User authentication docs to csrf_token not clear in User Authentication docs

Added a patch that adds info on the csrf_token and a link to upgrading instructions ahead of the form in question so it won't surprise people (as reported in this ticket).

comment:3 Changed 5 years ago by timo

  • Triage Stage changed from Accepted to Ready for checkin

comment:4 Changed 5 years ago by lukeplant

I think I disagree with Russell on this one. I'm kind of loathe to clutter up the auth documentation with notes about what the CSRF tag does, for the following reasons:

  • Adding documentation is always a balance - too much information about irrelevant things can really spoil the usefulness of docs.
  • If we add an explanation here, we need to add it every place in the docs (there are a few others already).
  • For existing developers, if they've read the release notes they'll know what the tag does.
  • For new developers, if they've read the tutorial they'll know what the tag does (or at least have some vague idea why it is there).
  • If developers see something like a template tag they don't understand, aren't they capable of looking it up in the template tag docs? We have this nice little search box...

I think the reaction of the reporter is over the top given these considerations. Ideally I'd like all template tags in code blocks to be hyperlinked to the docs for them, but from my initial investigations I don't think this would be easy.

comment:5 Changed 5 years ago by drozzy

How is my reaction "over the top"? A term is used in documentation that is never introduced first. There is even NO link leading to an explanation.
I still don't know what it does. And I don't consider myself a newbie user of django (granted I am not a django developer - but the manual is not for developers is it?)

I think you are not taking the feedback I am providing to you seriously here, but rather dismissing it as a "user error". But django docs are usually pretty good at explaining everything to you on the spot, without making you hunt for things (think msdn).

comment:6 Changed 5 years ago by lukeplant

Well, what is introduced 'first' depends on the order you read the documentation, doesn't it? And you are allowed to read it in any order. We cannot link to everything at every point, so we have an assumed order - we assume the user has at least read the tutorial, and has read the release notes for their current version if they started with Django a long time ago. With those assumptions, the tag has indeed been explained 'first'. You could have the same reaction about most of the other things in the example, like block and extends, which are equally mysterious if you haven't come across them before.

Also, the example code is presented as a block of code that can be copy-pasted into your template as a starting point. For that sort of thing, it is kind of besides the point to explain everything in it.

I am taking your feedback seriously, but there is a balance to strike, that's what I'm saying. I am surprised that you still don't know what the tag does. Have you tried to find out? Have you read the release notes for 1.2/trunk? If you are choosing to use trunk, and therefore are following trunk docs (and they are clearly labelled as such), then there is an additional burden on you as a developer to stay on top of recent changes - by reading the notes for trunk, for instance, or by taking some initiative to fill in gaps in your knowledge.

I'm also saying that by your argument we'd have to add the exact same patch to ref/contrib/formtools/form-wizard.txt and topics/i18n/internationalization.txt. Once you do that, you really start to question if that is the right approach.

Note I haven't changed the status of the bug because another core committer disagrees with me. Only if Russell changes his mind will the bug be closed as WONTFIX or whatever.

comment:7 Changed 5 years ago by russellm

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

In retrospect, I concur with Luke. but it's well documented as a standalone tag, in the release/upgrading notes, and in the tutorial. I don't think it's unreasonable to suggest that readers should have seen those documents before they see the auth topic guide; or if they haven't, that they should be able hunt down the appropriate reference to find out what the tag does. If you put csrf_token into the search field for the docs, the first result is extremely relevant.

As a case in point - the template sample doesn't describe how the {% url %} tag works, either; that doesn't mean we should include a pointer to how the {% url %} tag works.

I also agree with Luke that it would be good to have the tag itself act as a hyperlink to its own documentation, but I don't know how we could implement that within Sphinx.

comment:8 Changed 5 years ago by lukeplant

(In [13135]) Added hyperlinks for builtin template tags and filters to code samples in docs.

Implemented in javascript because doing it 'properly' is pretty much impossible with Sphinx and Pygments.

Refs #12249

comment:9 Changed 5 years ago by lukeplant

(In [13137]) [1.1.X] Added hyperlinks for builtin template tags and filters to code samples in docs.

Implemented in javascript because doing it 'properly' is pretty much impossible with Sphinx and Pygments.

Refs #12249

Backport of [13135] from trunk

comment:10 Changed 4 years ago by jacob

  • milestone 1.2 deleted

Milestone 1.2 deleted

Note: See TracTickets for help on using tickets.
Back to Top