#28582: Tutorial contains unnecessary explanation
-------------------------------------+-------------------------------------
Reporter: ImmaSix | Owner: ImmaSix
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.11
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
-------------------------------------+-------------------------------------
Description changed by ImmaSix:
Old description:
> 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,
> *
New description:
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?
--
--
Ticket URL: <https://code.djangoproject.com/ticket/28582#comment:1>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/064.1507c6398f4ca8d9b93aff26d2acabcf%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
