So I read the entire thread so far, and I saw some miscommunication induced hostility. I wasn't sure what was miscommunicated, just progressively more sure with each post that `something` had been miscommunicated. So I read the ticket... and I can see why it was rejected. Without at least some guidelines, rules, or procedures, a large community driven project like Django would wind up with a bug tracker totally out of hand. If the desired outcomes I have inferred from what your writing, here and in the ticket, are in fact what you hoped to achieve by creating the ticket, then might be in agreement with you on 'this is something to fix'. But I still think the wording you chose for the ticket, wasn't the right way to describe it.
Django has exceptional "User" documentation. A developer building things "with" Django, has high quality documentation on how to "use" Django. The overarching goal is to make "using" Django as easy for a developer as we can. Django has some good documentation on how to "begin" developing on the source code that makes up Django. It sounds like these are not the sort of documentation you are talking about. Which might be where the miscommunication is starting. Now, please correct me if I am wrong, but are you looking for a much more 'complete' set of 'internal' documentation so that you could for example open the 'internal documentation' for Form and BaseForm for 1.8 and 1.9 side by side and see any differences in how things constructed 'under the hood' ? It was described already in this thread as "Javadoc-style" but I think that missed the mark a bit. Are you trying to suggest something more like the output of sphinx apidoc (http://sphinx-doc.org/ext/autodoc.html#module-sphinx.ext.autodoc), where docstrings, class and method invocation parameters, and optionally even some of the inline comments inside a class or method, are assembled together to give you a way to see some of the information about how these pieces work, without going all the way to the level of detail you would have if you read the source code itself? I think there may be a concern that such information is covered in the section of the documentation that covers changes between each version. However I can also see the appeal of having the ability to view the differences between any versions of the code, particularly if trying to maintain or modernize an existing django based project or a reusable Django application/library, I think this sort of thing is at least worthy of discussion. Regards Sam On Saturday, 19 December 2015 08:02:56 UTC+8, 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/c172d499-8d35-40bc-972e-7219e3f887bd%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.