Documentation for custom related managers is contradictory

[Adam Alton]

In the [section of the "Managers" documenation about base managers](​https://docs.djangoproject.com/en/4.1/topics/db/managers/#django.db.models.Model._base_manager), it says:

By default, Django uses an instance of the Model._base_manager manager class when accessing related objects

and then two paragraphs further down it says:

Base managers aren’t used when querying on related models

What? So Django uses a base manager for related objects, but base managers aren't used for related objects?! I checked with a colleague and they couldn't make sense of it either.

It's unclear how to specify a custom manager which would be used for related object lookups. The section above about default managers doesn't give any clarifcation either.

I seem to remember that there used to be an attribute on the Manager class called use_for_related_objects, but looking in the Django source code I can't see any reference to that anymore.

I would open a pull request to update the docs, but I'm genuinely not sure what the behaviour is!

[Mariusz Felisiak]

What? So Django uses a base manager for related objects, but base managers aren't used for related objects?! I checked with a colleague and they couldn't make sense of it either.

We have here two different things::

• accessing related fields e.g. choice.question where the Model._base_manager manager class is used. This is because Django needs to be able to retrieve the related object, even if it would otherwise be filtered out (and hence be inaccessible) by the default manager (as documented).
• filtering out related fields e.g. Choice.objects.filter(question__name__startswith='What') where base managers aren’t used.

Personally, I find the documentation quite clear, it contains examples etc. I'm not sure how we could be clearer 🤔. Closing as a duplicate of #31342.

Docs improvements are always welcome so feel-free to submit PR with a concrete proposal and Refs #31342 -- ....