[Django] #20910: Documentation incomplete or misleading(?)
Django
-------------------------------+--------------------
Reporter: jggramlich@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.5
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: jggramlich@… | Owner: nobody
Type: Uncategorized | Status: closed
Component: Documentation | Version: 1.5
Severity: Normal | Resolution: needsinfo
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by timo):
* status: new => closed
* needs_better_patch: => 0
* resolution: => needsinfo
* needs_tests: => 0
* needs_docs: => 0
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:1>
Django
Reporter: jggramlich@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by anonymous):
* status: closed => new
* resolution: needsinfo =>
Comment:
...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?
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:2>
Django
Reporter: jggramlich@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:3>
Django
Reporter: jggramlich@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:4>
Django
Reporter: jggramlich@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (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/
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:5>
Django
Reporter: jggramlich@… | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.5
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (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.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:6>
Django
Reporter: jggramlich@… | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: tutorial | Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by mjtamlyn):
* keywords: => tutorial
* type: Uncategorized => Cleanup/optimization
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:7>
Django
--------------------------------------+------------------------------------
Reporter: jggramlich@… | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.5
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by mjtamlyn):
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:8>
Django
Reporter: jggramlich@… | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution:
Severity: Normal | Triage Stage:
Keywords: tutorial | Unreviewed
Easy pickings: 0 | UI/UX: 0
Changes (by anonymous):
* stage: Accepted => Unreviewed
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:9>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.5
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Easy pickings: 0 | UI/UX: 0
Changes (by timo):
* stage: Unreviewed => Accepted
Comment:
Sounds great to me!
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:10>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.5
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by EvilDMP):
Replying to [comment:4 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:11>
Django
Reporter: jggramlich@… | Owner: nobody
Type: | Status: new
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution:
Keywords: tutorial, afraid- | Needs documentation: 0
to-commit | Patch needs improvement: 0
Has patch: 0 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
Changes (by EvilDMP):
* cc: EvilDMP (added)
* keywords: tutorial => tutorial, afraid-to-commit
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:12>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: tutorial, afraid- | Needs documentation: 0
to-commit | Patch needs improvement: 0
Has patch: 0 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
* status: new => assigned
* owner: nobody => anonymous
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:13>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: tutorial, afraid- | Needs documentation: 0
to-commit | Patch needs improvement: 0
Has patch: 0 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
* owner: anonymous => nsmgr8
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:14>
Django
-------------------------------------+-------------------------------------
Reporter: jggramlich@… | Owner: nsmgr8
Type: | Status: assigned
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: tutorial, afraid- | Needs documentation: 0
to-commit | Patch needs improvement: 0
Has patch: 0 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
Comment (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
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:15>
Django
-------------------------------------+-------------------------------------
Reporter: jggramlich@… | Owner: nsmgr8
Type: | Status: assigned
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: tutorial, afraid- | Needs documentation: 0
to-commit | Patch needs improvement: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:16>
Django
-------------------------------------+-------------------------------------
Reporter: jggramlich@… | Owner: nsmgr8
Type: | Status: assigned
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: tutorial, afraid- | Needs documentation: 0
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
Changes (by timo):
* needs_better_patch: 0 => 1
Comment:
Comments for improvement on PR.
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:17>
Django
-------------------------------------+-------------------------------------
Reporter: jggramlich@… | Owner: nsmgr8
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Accepted
Keywords: tutorial, afraid- | Needs documentation: 0
to-commit | Patch needs improvement: 1
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"d07d6ae1167f93f2e88b3743c070003a66a31b35"]:
{{{
#!CommitTicketReference repository=""
revision="d07d6ae1167f93f2e88b3743c070003a66a31b35"
Fixed #20910 -- Added a "snippet" sphinx directive to allow prefixing a
filename.
Thanks Marc Tamlyn for the suggestion.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:18>
Django
-------------------------------------+-------------------------------------
Reporter: jggramlich@… | Owner: nsmgr8
Type: | Status: closed
Cleanup/optimization | Version: 1.5
Component: Documentation | Resolution: fixed
Severity: Normal | Triage Stage: Accepted
Keywords: tutorial, afraid- | Needs documentation: 0
to-commit | Patch needs improvement: 1
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
Comment (by Tim Graham <timograham@…>):
In
[changeset:"1be21651988374fc5b9b3cf8eb9afb76de229ff0/djangoproject.com"]:
{{{
#!CommitTicketReference repository="djangoproject.com"
revision="1be21651988374fc5b9b3cf8eb9afb76de229ff0"
Added CSS for sphinx snippet directive.
refs #20910.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:19>
Django
-------------------------------------+-------------------------------------
Type: | Nasimul Haque
Cleanup/optimization | Status: closed
Component: Documentation | Version: 1.5
Severity: Normal | Resolution: fixed
Keywords: tutorial, afraid- | Triage Stage: Accepted
to-commit |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"c49ea6f5911296dcb40190c905e38b43cdc7c7a3" c49ea6f5]:
{{{
#!CommitTicketReference repository=""
revision="c49ea6f5911296dcb40190c905e38b43cdc7c7a3"
Refs #20910 -- Replaced snippet directive with code-block.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:20>
Django
-------------------------------------+-------------------------------------
Reporter: jggramlich@… | Owner: M.
Type: | Nasimul Haque
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: tutorial, afraid- | Triage Stage: Accepted
to-commit |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Comment (by Tim Graham <timograham@…>):
In [changeset:"1853e2dbf2e290ec04e3389d523bbe4bad94a42e" 1853e2db]:
{{{
#!CommitTicketReference repository=""
revision="1853e2dbf2e290ec04e3389d523bbe4bad94a42e"
[2.1.x] Refs #20910 -- Replaced snippet directive with code-block.
Backport of c49ea6f5911296dcb40190c905e38b43cdc7c7a3 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/20910#comment:21>