id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
35335	"Update ""Enabling the sites framework"" documentation to reiterate the ability to use `get_current_site`"	Sam Darwin	sam darwin	"Hi,

I was recently implementing the Django ""sites"" framework on a website, and encountered issues with the documentation that could likely be improved.

1. It says ""To enable the sites framework, define a SITE_ID setting"".

I believe this is factually wrong. The latest and most modern way to use the framework is with `get_current_site(request)`, and in that case a SITE_ID will interfere. So, it should at least say ""(optional)"" there. Or even go further, and discourage setting a SITE_ID.   

2. Imagine someone is learning about the ""sites"" framework for the first time. If there is something sort of surprising or unusual about a feature, it would be helpful to comment on that, and not leave it ""implied"" or unstated. In this case, what I think is unexpected is when you read these instructions about SITE_ID, and you think ""ok, so how does this all work...."", is the fact you would need to run multiple app servers, multiple web servers. Not one server.   Not a few horizontally scaled replicas (which is often the scenario).  Rather, multiple distinct app servers, each with a separate SITE_ID. Yes, while this is ""implied"" by the current documentation, it would be even more clear to state ""you must run multiple actual servers.  One server isn't enough."".  

At the same time, that's inconvenient, right?  Which leads to the next point:

3.  Include a ""recommendation"" to the developer.  There is a choice between statically defining a SITE_ID in the config, or else dynamically ascertaining the SITE_ID by using  `get_current_site(request)`.  Since get_current_site is probably better, it wouldn't hurt to mention that. However the words ""recommend"" or ""recommendation"" do not appear on the page of documentation.

with that in mind, a proposed documentation update is covered in a new pull request https://github.com/django/django/pull/17977 .

Thanks."	Cleanup/optimization	assigned	contrib.sites	5.0	Normal			Sam Darwin	Accepted	1	0	0	1	0	0