Opened 7 years ago

Last modified 6 years ago

#28582 closed Cleanup/optimization

Tutorial contains unnecessary explanation — at Version 1

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?

Change History (1)

comment:1 by ImmaSix, 7 years ago

Description: modified (diff)
Note: See TracTickets for help on using tickets.
Back to Top