Opened 10 years ago
Closed 9 years ago
#24732 closed Cleanup/optimization (fixed)
Reorder tutorial to cover basics before bells and whistles
Reported by: | Carl Meyer | Owned by: | João Luiz Lorencetti |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Ready for checkin | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | yes | UI/UX: | no |
Description
(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?
Change History (16)
comment:1 by , 10 years ago
comment:2 by , 10 years ago
Easy pickings: | set |
---|---|
Triage Stage: | Unreviewed → Accepted |
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.
comment:3 by , 10 years ago
I should be able to do it, but it will take a couple weeks, could this delay be a problem?
comment:4 by , 10 years ago
Don't worry! Tickets often have a lifespan measured in months if not years.
comment:5 by , 10 years ago
Summary: | Remove most admin customization details from the tutorial → Reorder tutorial to cover basics before bells and whistles |
---|
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 :-)
comment:6 by , 9 years ago
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.
Where could we move this simple view part?
Before the 'Database setup'?
The problem with this is the warning message about unapplied migrations getting us back to the database stuff again.
What is the problem about moving the simple view before this point and just comment something like:
"Ignore the warning message for the moment, we'll take a look a it soon"?
Or maybe it should be before 'Creating models'? At this point the migrations are applied and the user knows about the runserver command.
comment:7 by , 9 years ago
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.
comment:8 by , 9 years ago
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.
comment:9 by , 9 years ago
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.
comment:10 by , 9 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
comment:11 by , 9 years ago
@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?
comment:12 by , 9 years ago
@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!
comment:13 by , 9 years ago
@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.
comment:14 by , 9 years ago
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.
comment:15 by , 9 years ago
Has patch: | set |
---|---|
Triage Stage: | Accepted → Ready for checkin |
Final review to be done tomorrow.
Alternatively, we could keep the content (since it's already written and a nice intro to admin customization), but move it to the end.