HI Doug, I can relate to what you are saying, I had a similar experience when trying to find a reference for the generic FormView. Issuing a P.R. to improve it is on my BLOTTD (big list of things to do). I was interviewing a candidate last week who knows I'm a big fan of Django, and wanted to throw a curveball, so I asked what they thought the biggest shortcoming of Django is. Without hesitation, they mentioned that their current team (which is just starting to learn Django) had trouble with the documentation. When I followed up, they mentioned it all seemed to be by example, rather than reference, and both are useful.
It is a big fish to fry, as Tim G mentioned, but I think it can be improved incrementally. I've used the Django Documentation for several years, and this is the first I've heard of the "topics", "reference" and "how-to". As someone who used PHP for years, one thing I always felt they got right was documentation. That may just be the way my mind works, however. This is a long way of saying, I'm interesting in helping out. Regards, Tim On Sunday, December 27, 2015 at 9:06:46 PM UTC-5, Doug Epling wrote: > > Tim -- > > Thank you so much for the link to that blog post. I am going away now to > think about that data a little, but I'll be back. > > I was not aware of the "topics", "reference", and "how-to" assortment. > But I have scanned the Table of Contents, and I find almost nothing here > addressing documentation > <https://docs.djangoproject.com/en/1.9/internals/>. > > I am afraid I have caused enough trouble for now. I need a little time to > digest that survey data, but I will be back. > > When I look at Django docs, I want to be informed as a Python programmer, > perhaps even a novice one. As far as I can tell, there is no such thing in > Django as Forms -- forms or form either for this matter. There is a Form > class, and it can instantiate any number of objects. But THIS KIND OF > THING (caps for emphasis on this example) is the kernel of my frustration. > > Again, many thanks Tim, your last post is very helpful to me. > > On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote: >> >> I filed bug report >> #25952 <https://code.djangoproject.com/ticket/25952>but apparently it >> was in the wrong place. And I referenced this post >> <https://groups.google.com/forum/#!searchin/django-users/documentation/django-users/1qHviCZMPJA/_8qVb0YYdhAJ>, >> >> but I was thinking it was this group ... I wonder how that happened? >> >> 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. >> >> It might also be helpful to evaluate how different audiences access the >> docs. Tutorials are great -- module and class libraries, not so much. >> >> With resulting user feedback along with expert categorization of >> documentation use cases, as with any writing exercise, there must be an >> outline. The existing outline might be a good place to start. >> >> Oh, and those pesky deadlines, when is v. 2.0 slated for release? >> >> >> -- You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at https://groups.google.com/group/django-developers. To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/025ed576-59e1-45cf-9cbe-be11ee56115d%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
