#25952: structural & functional review of django documentation
-------------------------------+--------------------------
Reporter: depling | Owner: nobody
Type: Bug | Status: new
Component: Documentation | Version: 1.9
Severity: Normal | Keywords: documetation
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/25952>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/050.750348a6e1c9a5fb18ddd64937413de2%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
