Groups keyboard shortcuts have been updated
Dismiss
See shortcuts

[Django] #35506: Rewrite confusing "URLconf" references in the Tutorial Part 1

19 views
Skip to first unread message

Django

unread,
Jun 8, 2024, 6:37:00 AM6/8/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: | Owner: lucas-r-oliveira
lucas-r-oliveira |
Type: | Status: assigned
Cleanup/optimization |
Component: | Version: dev
Documentation | Keywords: documentation,
Severity: Normal | tutorial, rewrite
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-------------------------------------+-------------------------------------
The term "URLconf" can be confusing and distracting for the user.
It is first mentioned with no context whatsoever, and it keeps getting
used throughout the tutorial.

As the tutorial progresses, it just keeps getting more and more confusing.
At first it may seem like it is a class. At a second glance, it may seem
like it's the name given to the urls.py file. At some point, it may even
look like it's each "path" inside the urlpatterns variable.

It is important to not confuse the user with too many technical terms at
this stage. Especially, since the user hasn't yet been able to see any
result once it gets here.

[https://docs.djangoproject.com/en/dev/intro/tutorial01/#write-your-first-
view]
--
Ticket URL: <https://code.djangoproject.com/ticket/35506>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

Django

unread,
Jun 8, 2024, 6:58:32 AM6/8/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation, | Triage Stage:
tutorial, rewrite | Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Lucas Oliveira):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:1>

Django

unread,
Jun 8, 2024, 11:35:16 AM6/8/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: documentation, | Triage Stage:
tutorial, rewrite | Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham):

I'm skeptical that the [https://github.com/django/django/pull/18240
proposed changes] are an improvement. It's important not to do too many
needless rewordings that require retranslation. I could see adding the
term "URLconf" to [https://docs.djangoproject.com/en/dev/glossary/ the
glossary].
--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:2>

Django

unread,
Jun 8, 2024, 5:08:41 PM6/8/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* keywords: documentation, tutorial, rewrite => tutorial
* stage: Unreviewed => Accepted

Comment:

Thank you Lucas for the report and Tim for the initial thoughts.

I generally agree that minimizing translation changes has high priority,
but in this particular case, where inexperienced users are reading the
tutorial for the first time (and even this is the first page), I think
that some in-place clarification is needed. I'm accepting the ticket on
that basis and also because:

1. When following the [https://diataxis.fr/ diátaxis] approach to writing
docs, a tutorial should be the smoother and simplest learning journey for
someone that is not familiar with the topic being presented, so jumps to
glossaries should be avoided.
2. After a very recent workshop from Daniele at DjangoCon Europe, the
Django tutorial was reviewed to spot parts that would benefit from some
improvements. This means that translation updates will be required in
these files nevertheless.
--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:3>

Django

unread,
Jun 8, 2024, 5:17:19 PM6/8/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:4>

Django

unread,
Jul 6, 2024, 5:17:10 AM7/6/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Lucas Oliveira):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:5>

Django

unread,
Jul 8, 2024, 3:39:51 PM7/8/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial urlconf | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* keywords: tutorial => tutorial urlconf
* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:6>

Django

unread,
Jul 11, 2024, 2:29:55 PM7/11/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial urlconf | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Natalia Bidart):

Fixed in 2c931fda5b341e0febf68269d2c2447a64875127
--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:7>

Django

unread,
Jul 12, 2024, 10:30:16 AM7/12/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial urlconf | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Tim Graham):

I believe it was a mistake to substitute a new, unfamiliar term "global
URLconf" for "root URLconf." The latter is used throughout the
documentation and has a setting named after it: `ROOT_URLCONF`.
[https://github.com/django/django/pull/18364 PR] to revert.
--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:8>

Django

unread,
Jul 12, 2024, 2:09:47 PM7/12/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: tutorial urlconf | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by GitHub <noreply@…>):

In [changeset:"dfd63ff43408e7901cc214b0482a7f844244d439" dfd63ff]:
{{{#!CommitTicketReference repository=""
revision="dfd63ff43408e7901cc214b0482a7f844244d439"
Refs #35506 -- Reverted "global URLconf" to "root URLconf" in tutorial 1.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:9>

Django

unread,
Jul 22, 2024, 11:30:58 AM7/22/24
to django-...@googlegroups.com
#35506: Rewrite confusing "URLconf" references in the Tutorial Part 1
-------------------------------------+-------------------------------------
Reporter: Lucas Oliveira | Owner: Lucas
Type: | Oliveira
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: tutorial urlconf | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* resolution: => fixed
* status: assigned => closed

--
Ticket URL: <https://code.djangoproject.com/ticket/35506#comment:10>
Reply all
Reply to author
Forward
0 new messages