Opened 3 months ago

Closed 2 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 Lucas Oliveira, 3 months ago

Has patch: set

comment:2 by Tim Graham, 3 months ago

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.

comment:3 by Natalia Bidart, 3 months ago

Keywords: documentation rewrite removed
Triage Stage: UnreviewedAccepted

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 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.

comment:4 by Natalia Bidart, 3 months ago

Patch needs improvement: set

comment:5 by Lucas Oliveira, 3 months ago

Patch needs improvement: unset

comment:6 by Natalia Bidart, 2 months ago

Keywords: urlconf added
Triage Stage: AcceptedReady for checkin

comment:7 by Natalia Bidart, 2 months ago

In 2c931fda5b341e0febf68269d2c2447a64875127:

Fixed 35506 -- Clarified initial references to URLconf in tutorial 1.

Last edited 2 months ago by Tim Graham (previous) (diff)

comment:8 by Tim Graham, 2 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:9 by GitHub <noreply@…>, 2 months ago

In dfd63ff:

Refs #35506 -- Reverted "global URLconf" to "root URLconf" in tutorial 1.

comment:10 by Natalia Bidart, 2 months ago

Resolution: fixed
Status: assignedclosed
Note: See TracTickets for help on using tickets.
Back to Top