Opened 7 years ago

Closed 5 years ago

#28582 closed Cleanup/optimization (wontfix)

Tutorial 01 and 02 cleanup suggestions

Reported by: ImmaSix Owned by: ImmaSix
Component: Documentation Version: 1.11
Severity: Normal Keywords:
Cc: Daniele Procida Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by ImmaSix)

working at write the docs conference with Daniele Procida. Work in progress, will add more notes here.

  • tutorial 01: "changing the port" block explanation not necessary - beginning users can skip this,
  • tutorial 01: "Projects vs. apps" block explanation not necessary.
  • tutorial 01: mysite/urls.py code snippets: the two code snippets are different from each other. The second adds not only the include as described in the tutorials, but also adds more lines that are not explained.
  • tutorial 01: explanation for include() a bit too detailed. A part of it can move to the include() reference if it isn't already there.
  • tutorial 01: a bit of explanation about the 'url()' arguments is well-suited. Some remarks:
  1. explanation about performance of regular expressions is not necessary.
  2. kwargs and name are not used in the example and are optional: can probably be removed.
  • tutorial 02: for a tutorial, it is ok to stick to the SQLite database. Any information about settings for other databases can be moved away. If it is important to set the database correctly this early in the project, I'd suggest to make a how-to and create a link to it.
  • tutorial 02: The content of the philosophy block might be moved to the main text, so that the main text is not interrupted by the block. Explaining why we create a model is important enough. If the explanation can be a bit shorter, that would be great.
  • tutorial 02: block bypassing manage.py is not necessary.
  • tutorial 02: the line @python_2_unicode_compatible # only if you need to support Python 2 comes a bit out of the blue. How important is this line?
  • tutorial 02: second time running python manage.py shell block is quite long. Maybe split it into multiple blocks and add explanation in between.

Change History (6)

comment:1 by ImmaSix, 7 years ago

Description: modified (diff)

comment:2 by ImmaSix, 7 years ago

Description: modified (diff)

comment:3 by ImmaSix, 7 years ago

Summary: Tutorial contains unnecessary explanationTutorial 01 and 02 cleanup suggestions

comment:4 by Daniele Procida, 7 years ago

Cc: Daniele Procida added

comment:5 by Claude Paroz, 7 years ago

Triage Stage: UnreviewedAccepted

comment:6 by Tim Graham, 5 years ago

Resolution: wontfix
Status: assignedclosed

Overall, I don't think these suggestions bring much value. The tutorial has served many users well for many years. It's not perfect but revisiting all these decisions seems unnecessary.

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