Re: [Django] #28582: Tutorial contains unnecessary explanation

[Django]

#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,
> * 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?

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?
 * tutorial 02: second time running `python manage.py shell` block is quite
 long. Maybe split it into multiple blocks and add explanation in between.

--

-- 
Ticket URL: 
Django 
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 django-updates+unsubscr...@googlegroups.com.
To post to this group, send email to django-updates@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django

Re: [Django] #28582: Tutorial contains unnecessary explanation

[Django]

#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: 
Django 
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 django-updates+unsubscr...@googlegroups.com.
To post to this group, send email to django-updates@googlegroups.com.
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.

[Django] #28582: Tutorial contains unnecessary explanation

[Django]

#28582: Tutorial contains unnecessary explanation
+--
   Reporter:  ImmaSix   |  Owner:  ImmaSix
   Type:  Cleanup/optimization  | Status:  assigned
  Component:  Documentation |Version:  1.11
   Severity:  Normal|   Keywords:
   Triage Stage:  Unreviewed|  Has patch:  0
Needs documentation:  0 |Needs tests:  0
Patch needs improvement:  0 |  Easy pickings:  0
  UI/UX:  0 |
+--
 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,
 *

-- 
Ticket URL: 
Django 
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 django-updates+unsubscr...@googlegroups.com.
To post to this group, send email to django-updates@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-updates/049.7a37e39cc13f1e951054ba9c8ec79894%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.