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
11864	Relationship backreference documentation is hard to find	anonymous	Derek Willis	"I would expect that documentation on backreferences in relationships would be documented under Model API documentation, but it takes a few clicks from there to see how it works.

http://docs.djangoproject.com/en/dev/topics/db/models/#relationships

will, if the seeker of wisdom is pretty sharp or diligent, lead to one link labeled ""the model field reference"", which if followed, takes one to

http://docs.djangoproject.com/en/dev/ref/models/fields/#foreign-key-arguments

From there, one follows a link labeled ""related objects documentation"" that points at 

http://docs.djangoproject.com/en/dev/topics/db/queries/#backwards-related-objects

which is where the fact that if I have a one-many relationship between Foo and Bar, where the Bar model class has a ForeignKey reference to Foo, then instances of the Foo
class will have an attribute named ""bar_set"" whose value is a relationship manager (and that fact's documented on a page about queries).  

All this means that the highly useful and important fact about how Django manages the relationship from Foos to Bars is two clicks and quite a bit of reading away from the starting point from learning about
relationships. It might be useful for newcomers to have a quicker path (perhaps including a sentence example of the form ""if a Car model has a ForeignKey reference to the Manufacturer model, then Manufacturer instances will have an attribute ""car_set"" that provides access to the related Car instances"") -- a natural place for this example might be under the docs for ForeignKey.related_name (http://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.ForeignKey.related_name), but as it's such a useful an interesting feature, if there's an even more prominent place to put it, so much the better.

thanks!





"		closed	Documentation	1.1		fixed	relationships foreigkey		Accepted	1	0	0	0	0	0