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.

Reply via email to