[Django] #24732: Remove most admin customization details from the tutorial
Django
------------------------------------------------+------------------------
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
(Credit to Ned Batchelder for pointing this out in IRC. He recommended the
Django tutorial to someone with a "and just skip all the stuff in part 2
about customizing the admin" caveat.)
The admin is cool, but it's not the core of Django. I think it's
definitely a nice "ooh shiny" win to play with the admin right after
writing a model, but part 2 of the tutorial then goes on a lengthy
"customizing the admin" digression, which I don't think is more important
than, say, learning how to write your own view.
I think we should cut out almost all the admin-customization content in
part 2 of the tutorial and replace it with a link to the appropriate admin
docs.
Thoughts?
--
Ticket URL: <https://code.djangoproject.com/ticket/24732>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: carljm | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by carljm):
Alternatively, we could keep the content (since it's already written and a
nice intro to admin customization), but move it to the end.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:1>
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Changes (by freakboy3742):
* easy: 0 => 1
* stage: Unreviewed => Accepted
Comment:
Moving it to the end would be my pick. It's still useful content, it's
just not the second most important thing to put in front of new users, and
it could be (and regularly is) confused as an indication that Django is a
CMS that can be configured, rather than an API toolkit.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:2>
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by dirtycoder):
I should be able to do it, but it will take a couple weeks, are you okay
with this delay?
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:3>
Django
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by aaugustin):
Don't worry! Tickets often have a lifespan measured in months if not
years.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:4>
Django
--------------------------------------+------------------------------------
Reporter: carljm | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by carljm):
Re-titling the ticket to reflect the intent to reorder the tutorial, not
remove content from it.
While we're reordering the tutorial, I also think we should move the first
bit of part 3 (writing your first simple view, without reference to
templates or models) before diving into writing a model. Django is a web
framework, which means its fundamental task is to take HTTP requests and
return responses, so that should be the first thing covered in the
tutorial. Models and templates are both secondary; they just provide
assistance in performing the core task. Thoughts?
@dirtycoder I wouldn't "reserve" the ticket (by assigning it to yourself)
until you actually begin work on it. If someone comes along tomorrow and
decides to tackle it, and you haven't started yet, they should be free to
do so. But as aaugustin says, this is quite unlikely; chances are very
good this ticket will still be sitting here waiting for you in a couple
weeks :-)
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:5>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by dirtycoder):
Great! :)
@carljm I agree with your comment about part 3, as a beginner who also
have pointed others beginners to the tutorial I was often asked about this
point. Some questions about Django being *only* suited for applications
using heavy database stuff.
I think we should provide the first portion of gratification as soon as
possible in the tutorial, so anyone starting will see the 'Hello World'
message and feel more motivated to dive in.
Maybe we could move this simple view part even before the 'Database
setup'?
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:6>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by carljm):
Yes, I'd be in favor of having the tutorial cover simple request/response
processing before it even discusses database setup. I've heard from more
than one person that having to figure out database setup right away
(before even seeing how basic request handling works) turned them off the
tutorial.
With modern Django the startproject template generates a working SQLite
config, so it's not necessary to dive into database setup before doing
anything else, as it used to be.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:7>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by carljm):
Oh, I missed your comment about the unapplied migrations warning. Hmm.
Maybe that is sufficient reason to do database stuff first. Though I also
think a note saying "ignore the warning about unapplied database
migrations for now; we'll deal with the database shortly" could be
adequate.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:8>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
--------------------------------------+------------------------------------
Comment (by dirtycoder):
Awesome, thanks for the reply.
I'll start working on it today.
If anyone does not appear contrary to that decision, I'll also move the
simple request/response part before the database setup and add a note
about the migration warning.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:9>
Django
Reporter: carljm | Owner:
Type: | dirtycoder
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Changes (by dirtycoder):
* owner: nobody => dirtycoder
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: carljm | Owner:
Type: | dirtycoder
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by dirtycoder):
@carljm My fork is at: https://github.com/dirtycoder/django
Part 1 of the tutorial is "finished", I'm reading the whole tutorial again
and following the instructions so it will take a few days to finish it.
I needed to make some minor charges to reflect the new order of some
parts. I also think the first introduction to the Admin should live
somewhere before the tests part, leaving only the look and feel
customization to the end. Thoughts?
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:11>
Django
-------------------------------------+-------------------------------------
Reporter: carljm | Owner:
Type: | dirtycoder
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by carljm):
@dirtycoder Great! Can you make a pull request of your changes? It's OK if
it's still a work-in-progress, you can note that in the title/description
of the pull request; it just makes it easier to review and comment on the
diff. You can always push more commits to the branch and the PR will
automatically update. Thanks!
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:12>
Django
-------------------------------------+-------------------------------------
Reporter: carljm | Owner:
Type: | dirtycoder
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by dirtycoder):
@carljm the PR is here: https://github.com/django/django/pull/4665
It's correct? I'll be off for two days, I'm back next week.
Thank you for the tips and patience.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:13>
Django
-------------------------------------+-------------------------------------
Reporter: carljm | Owner:
Type: | dirtycoder
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
Comment (by dirtycoder):
Splitted the admin part in two so it's easier for the reader follow along
without be intimidated by the admin customization, I also made a few minor
changes to the text to reflect the new order and while I was there, also
added some missing links.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:14>
Django
-------------------------------------+-------------------------------------
Reporter: carljm | Owner:
Type: | dirtycoder
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
* has_patch: 0 => 1
* stage: Accepted => Ready for checkin
Comment:
Final review to be done tomorrow.
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:15>
Django
-------------------------------------+-------------------------------------
Reporter: carljm | Owner:
Type: | dirtycoder
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"3653466bdf211ca603ec976c28d4a8da566dc671" 3653466b]:
{{{
#!CommitTicketReference repository=""
revision="3653466bdf211ca603ec976c28d4a8da566dc671"
Fixed #24732 -- Reordered tutorial to cover basics before bells and
whistles.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/24732#comment:16>