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
25952	structural & functional review of django documentation	Doug Epling	nobody	"I recently interviewed for a job calling for python and django.  I had not configured and used django since about v. 1.2 or 1.3.  

The current docs 'look' the same, but a bunch of things have changed.  And I found myself wandering around in the 1.8/1.9 docs trying to wrap my head around these changes.

That experience has left me with the notion that the documentation is out-of-control.  I could be wrong, but my sense is that things have deviated from journalistic principles at the heart of django.  

I am guessing this could have happened slowly as the software has developed along with attendant patchwork to the docs.  Also, it appears that in the effort to make docs beginning user friendly, they have become unorganized from the perspective of someone with more wherewithal than the beginner.

I know I will get flack for this long winded and generalized bug report.  It is also clear to me that I am a newbie around here.  But here's the thing:  With wading through all the suggested required reading on this topic (much like many django topics) making a suggestion could take forever.

So I am hereby suggesting that the road map for the v. 2.0 release include revamped documentation.  It should begin as soon as possible with the somewhat standard best practice of collecting ""find what you were looking for"" or ""was this page helpful"" or ""rate this page on its organization, clarity, brevity, etc."" data on every single existing page.  

And I might be inclined help-out on the team working on this type of initiative (especially if I should be hired for that django job I mentioned).  By-the-way I think part of the reason this manager is looking to hire is because she has been given django to work-with and has found its documentation unfathomable -- even mentioning the option of using something else.

  "	Bug	closed	Documentation	1.9	Normal	fixed	documetation		Unreviewed	0	0	0	0	0	0