#28625 closed Cleanup/optimization (fixed)
DATABASES TIME_ZONE setting may be confused with TIME_ZONE
| Reported by: | Jon Ribbens | Owned by: | Jon Ribbens |
|---|---|---|---|
| Component: | Documentation | Version: | 1.11 |
| Severity: | Normal | Keywords: | |
| Cc: | Triage Stage: | Accepted | |
| Has patch: | yes | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | yes | UI/UX: | no |
Description
The documentation at https://docs.djangoproject.com/en/1.11/ref/settings/#time-zone is spectacularly unclear that it's talking about the TIME_ZONE sub-setting of the DATABASES setting, and not the top-level TIME_ZONE setting.
Change History (9)
comment:1 by , 7 years ago
| Triage Stage: | Unreviewed → Accepted |
|---|
comment:2 by , 7 years ago
| Owner: | changed from to |
|---|---|
| Status: | new → assigned |
comment:4 by , 7 years ago
| Summary: | TIME_ZONE documentation is spectacularly unclear → DATABASES TIME_ZONE setting may be confused with TIME_ZONE |
|---|---|
| Type: | Bug → Cleanup/optimization |
Perhaps you could clarify how the confusion arose. I'm not immediately convinced that a call out box is needed. My guess is that you used "find" in a browser and encountered this as the first result. I think upon reading the section, especially the second sentence, "The same values are accepted as in the general TIME_ZONE setting." there's not much chance of confusion.
Similar clashing names existing elsewhere, for example, CACHES['BACKEND'] and TEMPLATES['BACKEND'], so if this is really a problem, it could be nice to find a more general solution.
comment:5 by , 7 years ago
There's a general principle of course that if you are an expert in something it can be very hard to know what will and will not be obvious to non-experts. I couldn't comment on the probability of confusion in general, all I can offer is the sure and certain fact that I was indeed confused and it caused me a noticeable amount of wasted time trying to work out how I was supposed to get times to be displayed in my chosen time zone and investigating what I was supposed to do about TIME_ZONE having been set by django-admin startproject in apparent contradiction to the documentation which seemed to say that it must not be set if USE_TZ is set (since I'm using PostgreSQL).
comment:6 by , 7 years ago
Why do you think "The same values are accepted as in the general TIME_ZONE setting." didn't give a clue? Maybe it would be sufficient to add some clarification to that sentence, e.g. This inner option of DATABASES accepts the same values as the general TIME_ZONE setting."
Another option could be to prefix all the dictionary setting headers so it appears as something like DATABASES: TIME_ZONE, but that would make the table of contents less clean.
My goal is to find a solution that doesn't add too much extra verbosity for someone reading the DATABASES setting docs from top to bottom compared to someone skimming the docs.
comment:7 by , 7 years ago
It didn't give a clue because I didn't know that there are two different TIME_ZONE settings, so that sentence was meaningless to me; the phrase "the general TIME_ZONE setting" tells you nothing if you don't know that what you're looking for is the "general TIME_ZONE setting" and not whatever unexplained thing this is that you're looking at.
The CACHES.BACKEND and TEMPLATES.BACKEND settings don't have the same confusion as neither of them is a "general" setting and each of them starts with the words "The cache backend to use" or "The template backend to use" so there's no way you could be looking at one thinking it's the other.
This is a spectacularly good point ;-) Would you like to submit a PR?