Reorder tutorial to cover basics before bells and whistles

[Carl Meyer]

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

[Carl Meyer]

Alternatively, we could keep the content (since it's already written and a nice intro to admin customization), but move it to the end.

[Russell Keith-Magee]

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.

[João Luiz Lorencetti]

I should be able to do it, but it will take a couple weeks, could this delay be a problem?

[Aymeric Augustin]

Don't worry! Tickets often have a lifespan measured in months if not years.

[Carl Meyer]

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 :-)

[João Luiz Lorencetti]

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.

[Carl Meyer]

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.

[Carl Meyer]

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.

[João Luiz Lorencetti]

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.

[João Luiz Lorencetti]

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

[Carl Meyer]

@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!

[João Luiz Lorencetti]

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

[João Luiz Lorencetti]

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.

[Tim Graham]

Final review to be done tomorrow.

[Tim Graham <timograham@…>]

In 3653466b:

Fixed #24732 -- Reordered tutorial to cover basics before bells and whistles.