structural & functional review of django documentation

[Doug Epling]

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.

[Tim Graham]

Feel free to propose an action plan on the DevelopersMailingList but you are correct that this type of grand suggestion with no concrete steps to move forward isn't appropriate for a Trac ticket. Thanks!

[Doug Epling]

Right, well, thanks, I did look there, and there is an un-addressed thread from earlier this year.

Also, I think I did suggest an action plan, which I will repost to the end of that un-addressed thread.

Thanks,