Re: [Django] #35335: Update "Enabling the sites framework" documentation to reiterate the ability to use `get_current_site`

[Django]

#35335: Update "Enabling the sites framework" documentation to reiterate the
ability to use `get_current_site`
-------------------------------------+-------------------------------------
Reporter: Sam Darwin | Owner: sam
Type: | darwin
Cleanup/optimization | Status: assigned
Component: contrib.sites | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Sam Darwin):

> too opinionated, and
> contrasts with the intentional neutrality

In the world of software though, it's often possible that new libraries
are introduced, new features are created, and then the general consensus
is that you ought to tend towards the new method. Meanwhile, the earlier
techniques can pass through phases where they are discouraged, deprecated,
and finally obsolete and not supported at all.

Consider this quote, from a web search:

> The os.system function is easy to use and interpret: simply use as input
of the function the same command you would use in a shell. However, it is
deprecated and it is recommended to use subprocess now.

Is it not true, that `subprocess` is recommended, while `os.system` is
deprecated?

Or that Python 2 is completely unsupported, while the choice of Python 3
is strongly recommended (compared to Python 2) ?

It depends on the method in question. If `get_current_site(request)` is
newer and has more robust features than `get_current()`, then it could be
analogous to `os.system` versus `subprocess`. Certain options actually
can become deprecated and/or recommended. And when that occurs, it isn't
lacking in neutrality to discuss them.
--
Ticket URL: <https://code.djangoproject.com/ticket/35335#comment:2>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35335: Update "Enabling the sites framework" documentation to reiterate the
ability to use `get_current_site`
-------------------------------------+-------------------------------------
Reporter: Sam Darwin | Owner: sam
Type: | darwin
Cleanup/optimization | Status: assigned
Component: contrib.sites | Version: 5.0
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Sam Darwin):

The sites framework is unusual and a bit challenging to document, because
of the following reason. Typically, if there is a feature, you'd explain
how to use the functionality to an audience who is planning on using it.
The instructions are aimed at that group: the actual users. For those who
aren't going to use the feature, they can skip the page entirely.

Conversely, with the "sites" framework, 90% of users aren't going to use
the "sites" framework in the sense of having multiple sites, however they
may reference the documentation because it is recommended for most or all
Django deployments to enable "sites" as a best-practice.

Documentation should be geared toward the main, largest, set of users who
will need to read it.

In this case, that would be the not-actual-users of the sites framework,
who are enabling it because of best-practices, but not running multiple
sites.

Ultimately the docs ought to assist both of these groups: the "real
users", and the most common group of users.

With that in mind, in the pull request, I added an "Installation
Scenarios" section, with two different scenarios, corresponding to the
above mentioned groups.

Your feedback has been helpful. I think that it's not a situation where
one method is always recommended, or the other, but it depends on the
case.
--
Ticket URL: <https://code.djangoproject.com/ticket/35335#comment:3>