Rewrite reference to model manager usage to avoid saying "tricky"

[Jacob Walls]

In the ​database optimization doc, there is this advice:

Understand select_related() and prefetch_related() thoroughly, and use them:

• in managers and default managers where appropriate. Be aware when your manager is and is not used; sometimes this is tricky so don’t make assumptions.

Saying something is "tricky" and immediately moving on leaves the impression of information hiding. Let's at least link to something that explains what to watch out for or debug. In other words, we need to answer the question, "wait, when wouldn't my model manager be used"?

(The location of this text is moving in #28586.)

[Natalia Bidart]

Thank you Jacob, I agre that this change will make these docs more approachable and less scary. I think the original Component set to ORM is correct, since we tend to use "Documentation" for tickets around the process of building/handling docs, not the doc content itself.

[Jacob Walls]

Super, thanks for confirming.

we tend to use "Documentation" for tickets around the process of building/handling docs, not the doc content itself.

You bring up a long-time point of confusion for me. Elsewhere like the Trac reports, it's implied that the documentation component includes doc content, e.g. "Documentation patches that need review" or "Documentation tickets that need patches". I wouldn't expect those to only link to sphinx/infra related tickets.

[Segni Mekonnen]

Working on this ticket. Will submit PR shortly.

This ticket asks to replace vague "tricky" language with specific examples
of when managers are not used. Planning to provide concrete examples like
instance access (raises AttributeError) and related field access that may
bypass custom manager methods.

[Tim Graham]

Unless the longstanding process has recently changed without my knowledge, the component for documentation patches that don't need code changes is indeed "Documentation".

[Segni Mekonnen]

PR submitted: ​https://github.com/django/django/pull/19962

The fix replaces the vague "tricky" language with specific examples:

• Instance access raises AttributeError (blog_instance.objects)
• Related field access may bypass custom manager methods
• Added reference to queries documentation for more details

Ready for review.

[Segni Mekonnen]

Hi @jacobtylerwalls, I've addressed the cross-reference and line length issues that were causing CI failures. The documentation now explains the base manager vs default manager distinction you mentioned, with a link to the managers documentation. All CI checks should be passing now. Let me know if you need any other adjustments!

[Jacob Walls <jacobtylerwalls@…>]

In b1e0262c:

Fixed #36665 -- Improved manager usage guidance in docs/topics/db/optimization.txt.

[Jacob Walls]

Not backporting as the location of this text moved in main (6.1), and it's only a minor edit.