Opened 6 months ago
Closed 5 months ago
#35506 closed Cleanup/optimization (fixed)
Rewrite confusing "URLconf" references in the Tutorial Part 1
Reported by: | Lucas Oliveira | Owned by: | Lucas Oliveira |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | tutorial urlconf |
Cc: | Triage Stage: | Ready for checkin | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | yes | UI/UX: | no |
Description
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
Change History (10)
comment:1 by , 6 months ago
Has patch: | set |
---|
comment:2 by , 6 months ago
comment:3 by , 6 months ago
Keywords: | documentation rewrite removed |
---|---|
Triage Stage: | Unreviewed → Accepted |
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:
- When following the 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.
- 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.
comment:4 by , 6 months ago
Patch needs improvement: | set |
---|
comment:5 by , 6 months ago
Patch needs improvement: | unset |
---|
comment:6 by , 5 months ago
Keywords: | urlconf added |
---|---|
Triage Stage: | Accepted → Ready for checkin |
comment:7 by , 5 months ago
In 2c931fda5b341e0febf68269d2c2447a64875127:
Fixed 35506 -- Clarified initial references to URLconf in tutorial 1.
comment:8 by , 5 months ago
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
. PR to revert.
comment:10 by , 5 months ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
I'm skeptical that the 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 the glossary.