The use of related_name kwarg in ForeignKey should be mentioned in the Many-to-One documentation

[Ty K]

In this article:​https://docs.djangoproject.com/en/3.2/topics/db/examples/many_to_one/ on Many-To-One models it seems odd that related_name is never mentioned. I think it's fairly important to know what seems from what little I've seen so far in practice the most common practice used to access the Many side of the house through the One in that arrangement, not the way demonstrated in the article.

As a beginner that I first went there trying to figure out how to create a Many-To-One relationship for my app and was very confused after reading through it and not finding anything alluding to the concept except through objects, since I knew it existed but simply couldn't remember the argument. It seems like a pretty important detail.

[Carlton Gibson]

There are several examples using the related descriptor on that page. e.g.:

Create an Article via the Reporter object:

>>> new_article = r.article_set.create(headline="John's second story", pub_date=date(2005, 7, 29))
>>> new_article
<Article: John's second story>
>>> new_article.reporter
<Reporter: John Smith>
>>> new_article.reporter.id
1

Search for article_set.

The ​linked ForeignKey docs specify the related_name parameter, and the full discussion is in the ​Related objects section of the Making Queries topic page.

I appreciate that the ORM API is complex, and takes time to fully internalise but I'm not sure that in context complicating the Many-to-one relationships examples with a custom related_name here is the right way to go.