Re: FK constraints are not checked at the end of nested atomic blocks

[Anssi Kääriäinen]

On Tuesday, December 22, 2015 at 1:20:23 AM UTC+2, Shai Berger wrote:
>
> > We could add a documented API to check wanted models for foreign key 
> > constraint violations (.check_constraints(Model1, Model2) would be a 
> > likely API). Then lets just document that depending on the database 
> > this check can be slow. On some databases we can get away with SET 
> > CONSTRAINTS IMMEDIATE 
> > [http://www.postgresql.org/docs/9.1/static/sql-set-constraints.html], 
> > which should be fast. 
>
> Then why don't we implement check_constraints() as 
> "SET CONSTRAINTS IMMEDIATE; SET CONSTRAINTS DEFERRED" on PG? That is 
> documented to only check outstanding changes in the transaction. 
>
> I am not sure about the performance implications on Oracle, but the Oracle 
> docs suggest "Making constraints immediate at the end of a transaction is 
> a 
> way of checking whether COMMIT can succeed."[1] 
>
> As far as I know, neither MySql nor Sqlite support deferrable constraints. 
>

Hmmh, if we only need to check deferred constraints, this can be made to 
work. I don't believe SET CONSTRAINTS is expensive at all, it does the same 
job the DB needs to do at commit time in any case.

Using SET CONSTRAINTS ALL IMMEDIATE; SET CONSTRAINTS ALL DEFERRED; is a bit 
problematic, as any constraint that was DEFERRABLE INITIALLY IMMEDIATE 
would then be set to deferred mode after the commands. This isn't a big 
problem in practice, unless we at some point allow creating DEFERRABLE 
INITIALLY IMMEDIATE constraints. We could also explicitly name all the 
constraints we want to defer, but I'm not sure if we actually reliably know 
the names of the constraints.

So, we could add a flag "check_deferred_constraints" to atomic(), and use 
the above SET CONSTRAINTS commands to achieve the wanted results. We will 
likely need to document that DEFERRABLE INITIALLY IMMEDIATE constraints 
will be set to deferred mode.

 - Anssi

-- 
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/ecb654fc-42cc-4310-a849-a320e42bf0b7%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Doug Epling]

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 .  


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 but apparently it was 
> in the wrong place.  And I referenced this post 
> ,
>  
> 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/627694e7-502e-4b1e-9c6b-b7bd78da8653%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Proposal: by default, don't populate a modelformset with all model instances.

[Russell Keith-Magee]

On Sun, Dec 27, 2015 at 11:00 PM, Wim Feijen  wrote:

> By default, when you create a formset from a model, the formset will use a
> queryset that includes all objects in the model (e.g.,
> Author.objects.all()).
>
> In most use cases, people will want to use a specific subset of data and
> will construct queryset by hand. Or they want to use an empty queryset,
> just to add data.
>
> In my opinion it would be better to set the empty queryset as a default.
>
> Do you agree?
>

I think both potential defaults are completely arbitrary. One represents
“Edit everything that is currently available”; the other represents “Give
me the ability to add new things”. Which one is a “more appropriate”
default will ultimately come down to your own use cases.

However, even if your *were* completely correct in saying that the second
interpretation was a more common one, it would be exceedingly difficult to
make this change because of backwards compatibility. For that reason alone,
I’d suggest that this proposal isn’t likely to go very far.

Yours,
Russ Magee %-)

-- 
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/CAJxq84-eXPiJQ35gJVkR7K%2BfdVD4YVG48sx8RX7F4Wdzyzms7A%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Graham]

Adding a survey link is not difficult. We conducted a community survey [1] 
earlier this year with one question related to documentation, "What parts 
of the Django documentation do you find most useful?" What questions to ask 
and how to turn the answers into actionable items is the part I'm not sure 
about and maybe you could advise on.

In my view, Django's docs haven't strayed from the "topics", "reference", 
and "how-to" division that we've had since 1.0 or so. Are you aware of this 
grouping? Maybe a "how the docs are organized" section on the index page 
would help communicate that and make it more intuitive where to look for 
something?

I'll admit I'm skeptical of a wholesale reorganization to this structure 
for several reasons:
1. It'll be confusing for existing users who are familiar with the current 
section.
2. It'll make it more difficult or impossible to backport documentation 
enhancements to the stable version of the docs (assuming we don't also 
reorganize them with same structure)
3. It'll create an opportunity for broken links (obviously we could 
mitigate this to some extent by adding redirects to the new locations).

It seems to me you were pretty close to finding what you were looking for 
at https://docs.djangoproject.com/en/1.9/ref/forms/ (first bullet, I 
think), but I didn't understand what you meant by the page being "the Joy 
of Cooking with Django."

[1] https://www.djangoproject.com/weblog/2015/may/07/community-survey/

On Sunday, December 27, 2015 at 2:47:35 PM UTC-5, Doug Epling wrote:
>
> Again, I am sorry if my comments have ruffled anyone's feathers.  I am not 
> going to argue.  My sole intent is a positive one.  And, indeed, I am 
> humbled by the ongoing work of this community over a period of time that I, 
> until now, have not been involved.
>
> I beleive, it is my impression, that between Django 1.1 and now, on the 
> verge of its second major version, there has been a tremendous amount of 
> Python software develpment.  And the internal commenting as well as the 
> public documentation has trailed along ad hoc.
>
> It can be said without legitimate reproach that any system whether it is 
> thermodynamics or a system of communication, such as our documentation, 
> will naturally tend toward entropy unless something actively intervenes. 
>  And we have developed a fairly complex system compared to, say, werksgeud. 
>
> That patchwork approach has disrupted a flow of utility for users in both 
> public documentation and internal commenting.  If this is true, Django has 
> strayed from principles of its foundation.  And our motto: "The framework 
> for perfectionists with deadlines."; holds true only until fininding 
> oneself lost in the documentation.
>
> Tim is exactly right; this is with no doubt a non-trivial issue.  Is 
> Django capable of tackling non-trivial issues?  If not I am in the wrong 
> place (a challenge to Django, relax, it's not personal) because I believe 
> Django should be setting the standard.  And this issue will not be resolved 
> by an ad hoc approach; meaning our traditional methodology of a problem 
> ticket reporting process is not amenable.  This calls for something else if 
> it calls for anything.
>
> However, Wim has a good idea!  Some exploratory research is a very 
> reasonable first step toward an objective problem definition.  Tim, how 
> hard would it be to present every visitor to the documentation with a 
> pop-up (or some other kind of) general invitation to visit a link on Survey 
> Monkey to help us with some feedback?
>
> On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote:
>>
>> I filed bug report 
>> #25952 but apparently it 
>> was in the wrong place.  And I referenced this post 
>> ,
>>  
>> 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 re

Re: structural & functional review of django documentation

[Doug Epling]

Again, I am sorry if my comments have ruffled anyone's feathers.  I am not 
going to argue.  My sole intent is a positive one.  And, indeed, I am 
humbled by the ongoing work of this community over a period of time that I, 
until now, have not been involved.

I beleive, it is my impression, that between Django 1.1 and now, on the 
verge of its second major version, there has been a tremendous amount of 
Python software develpment.  And the internal commenting as well as the 
public documentation has trailed along ad hoc.

It can be said without legitimate reproach that any system whether it is 
thermodynamics or a system of communication, such as our documentation, 
will naturally tend toward entropy unless something actively intervenes. 
 And we have developed a fairly complex system compared to, say, werksgeud. 

That patchwork approach has disrupted a flow of utility for users in both 
public documentation and internal commenting.  If this is true, Django has 
strayed from principles of its foundation.  And our motto: "The framework 
for perfectionists with deadlines."; holds true only until fininding 
oneself lost in the documentation.

Tim is exactly right; this is with no doubt a non-trivial issue.  Is Django 
capable of tackling non-trivial issues?  If not I am in the wrong place (a 
challenge to Django, relax, it's not personal) because I believe Django 
should be setting the standard.  And this issue will not be resolved by an 
ad hoc approach; meaning our traditional methodology of a problem ticket 
reporting process is not amenable.  This calls for something else if it 
calls for anything.

However, Wim has a good idea!  Some exploratory research is a very 
reasonable first step toward an objective problem definition.  Tim, how 
hard would it be to present every visitor to the documentation with a 
pop-up (or some other kind of) general invitation to visit a link on Survey 
Monkey to help us with some feedback?

On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote:
>
> I filed bug report 
> #25952 but apparently it was 
> in the wrong place.  And I referenced this post 
> ,
>  
> 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/373526bb-be5e-4ca0-b5cb-2ae558c996b8%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Graham]

My main concern is that it will be non-trivial to setup that type of 
feedback system, and I'm not sure how we would go about turning that type 
of data into actionable tickets. If anyone has experience with such a 
system, I'd be interested to hear about it.

On Sunday, December 27, 2015 at 10:19:05 AM UTC-5, Wim Feijen wrote:
>
> Hi Doug,
>
> I get lost regularly in Django's docs as well, so you are not alone there. 
>
> I think it is a good proposal to add:
>  "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 of the documentation. 
>
> I think it is a good thing to accumulate data. And if some page turns out 
> to be really bad or not helping, we have a choice to act on it.
>
> For me, that would be a good ticket which I would definitely accept, 
> because the scope is small and clear and it is something we agree on. The 
> best way to proceed in my opinion is to create an new ticket, to keep it 
> clear. Do you want to create this ticket?
>
> I have some other ideas on how to improve the documentation and layout as 
> well, but that is for another time.
>
> Bye, Wim 
>
>  
>

-- 
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/5e3ad3cf-d822-455f-862e-12cedfe8bb5f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Wim Feijen]

Hi Doug,

I get lost regularly in Django's docs as well, so you are not alone there. 

I think it is a good proposal to add:
 "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 of the documentation. 

I think it is a good thing to accumulate data. And if some page turns out 
to be really bad or not helping, we have a choice to act on it.

For me, that would be a good ticket which I would definitely accept, 
because the scope is small and clear and it is something we agree on. The 
best way to proceed in my opinion is to create an new ticket, to keep it 
clear. Do you want to create this ticket?

I have some other ideas on how to improve the documentation and layout as 
well, but that is for another time.

Bye, Wim 

 

-- 
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/39421256-8911-4fc7-800d-93d29a091d92%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Proposal: by default, don't populate a modelformset with all model instances.

[Wim Feijen]

By default, when you create a formset from a model, the formset will use a 
queryset that includes all objects in the model (e.g., Author.objects.all()
). 

In most use cases, people will want to use a specific subset of data and 
will construct queryset by hand. Or they want to use an empty queryset, 
just to add data.

In my opinion it would be better to set the empty queryset as a default. 

Do you agree?

Then I will make a ticket and maybe add a patch.

-- 
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/8f172935-bacf-4882-b668-01b001ae467a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: argon2 PasswordHasher

[Florian Apolloner]

I do not see anything wrong in the PR and there is probably no reason not 
to include it. It would be great if you could get feedback from dstufft 
and/or hynek in #cryptography-dev -- not that we miss something.

Cheers,
Florian

On Sunday, December 27, 2015 at 12:36:02 AM UTC+1, Bas Westerbaan wrote:
>
> Hello,
>
> This morning I submitted a Pull Request[1], which adds a PasswordHasher 
> for argon2 – the winner of the Password Hashing Competition.[2]  Tim Graham 
> mentioned I should send an e-mail to this list to discuss it.
>
> The patch is mostly pretty straight-forward.  I would like to add a few 
> remarks on some of the choices.
>
> 1. There are two Python packages that implement argon2.  Both bind 
> libargon2[3].  The first is argon2_py[4], which uses ctypes.  The second is 
> argon2-cffi[5], which uses... cffi.  Bindings using cffi are more portable, 
> so I choose argon2-cffi.
>
> 2. argon2 has four parameters: (i) variety ("type"), (ii) time cost ("t"), 
> (iii) memory cost ("m") and (iv) parallelism ("p").  There are two 
> varieties: argon2i and argon2d.  The first (argon2i) is safest against 
> side-channel attacks.  The second tries less hard to be secure against 
> side-channel attacks in favour of being more resilient against GPU 
> brute-forcing.  For web-apps, the first "argon2i" is the clear choice.  For 
> the other parameters I choose to use the same defaults as of argon2-cffi: 
> t=2, m=512, p=2.  On a i7-4790 @ 3.6Ghz the hash takes around 2ms to 
> compute.
>
> Best wishes,
>
>   Bas
>
>
>
> [1] https://github.com/django/django/pull/5876
> [2] https://password-hashing.net
> [3] https://github.com/p-h-c/phc-winner-argon2
> [4] https://github.com/flamewow/argon2_py
> [5] https://github.com/hynek/argon2_cffi
>

-- 
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/9a3378d2-3a8b-4bd9-b1e0-d64e25475d02%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: MOSS Award to Django

[Andrew Godwin]

On Sun, Dec 27, 2015 at 7:53 AM, Samuel Bishop  wrote:

> Once again I have to thank you for taking the time to keep replying. These
> longer explanations are proving very helpful (at least to me) in
> understanding Django Channels. :-)
>
> I definitely understand the compatibility reasons, I'm also pleased to see
> that signalling via a channel will be as simple as I had hoped, at least
> simple as long as we put aside compatibility issues with Django's built in
> signals. I'd still be pleased with only the ability to make my custom
> signals asynchronous.
>

Yes, the built-in signals have to remain as they are now; it is possible we
could hook something into the existing Signal code to provide an option to
run them via Channels, but I think the API to just make a new channel and
send events to it is actually easier and better anyway.

(I've never really liked the implicitness of channels, and the "come-from"
rather than "go-to" nature so you can't tell what code a signal invocation
might send without searching, whereas channel registrations are explicit in
a big dict)


>
> Digging into the implementation details, you've sparked my curiosity. For
> some reason the simplicity of the having just send() and receive_many()
> didn't fully dawn on me until now. Once I've made progress with my
> decoupling, I think I'll have to try experiment with cleaving the major
> parts of the entire request/response cycle into a chain of asynchronous
> actors.
>

Yup; in fact, I'm working on a spec, alongside development efforts, to
exactly lay out what the low-level API will be that everything runs on,
which is currently nicknamed "ASGI":
http://channels.readthedocs.org/en/latest/asgi.html

Django will run directly on top of that, with a small bit of code that
transforms send/receive_many into the documented consumer functions, but it
means there's flexibility to use the low-level API more directly in some
fashion if you want; since Channels is going to result in multiple projects
all cross-communicating already, I figured having a spec would be Very
Useful.


> I'll likely test how hard it is to 'wrap' each part of the cycle in a way
> that allows it to be called by synchronously or asynchronous code. I'd like
> to avoid creating "yet another async django, that isnt really django
> anymore", keep the existing synchronous code pathway seems like a good
> start at a "useful experiment".
>

I am curious to see what you could achieve with more atomic breakdown of
Django view processing; things like template rendering can definitely be
done separately, while I'm less sure about the ORM (as you can't collect
results from multiple channels at once in Channels for performance reasons;
all you can do is listen for a single event on a single channel and react
to it before you get the next event).


>
> As for 'could you call the end result Django'... I think "Django" is
> whatever we make of it ;-)
> I don't see why we wont still call the combination of all the parts, the
> ecosystem of compatible libraries, etc, "Django", regardless of how much we
> might change between now and far future versions like 4.0 or 9.0.
>

Well, "Django" is also something that's agreed upon by the community, the
Technical Board, and keeps to its promises of ease of use, backwards
compatibility, good documentation and so forth. Any radical change that
might end up happening would have to happen in slow steps over many
releases, and only with the buy-in of the community - I don't even fully
have that yet, and I don't expect to get it until Channels can show that it
works, is backwards-compatible, and solves issues without making anything
worse.

Andrew


> On Monday, 21 December 2015 19:31:54 UTC+8, Andrew Godwin wrote:
>>
>>
>>
>> On Mon, Dec 21, 2015 at 6:05 AM, Samuel Bishop 
>> wrote:
>>
>>> Hi Andrew,
>>>
>>> Thanks for the detailed response. I'm glad to hear you have tried a few
>>> different ways to implement this, and having read through your reply, and
>>> the channels docs again, I have more questions :-)
>>>
>>> Your point about asynchronous code introducing needless complexity is
>>> very well founded, its one of the reasons I like Actor Model Concurrency
>>> over other concurrency models, it scales well computationally, and
>>> *mentally*, as a programmer, I am trying break down my real world goals
>>> into discrete steps of computations, comparisons, iterations and by
>>> combining these steps, I construct my program. Actor Model Concurrency, is
>>> no more complicated than saying "This step can be done without affecting
>>> anything else thats going on", which makes the 'actor/task' much easier to
>>> introduce to existing synchronous code than most other concurrency methods.
>>>
>>
>> I agree - I'm a big fan of actors in general and it's usually what I turn
>> to to write complex simulations when I'm mucking around with game backends.
>>
>>
>>>
>>> One thing that sticks with me as I think about the current channels
>>> design, relates to 

Re: structural & functional review of django documentation

[Samuel Bishop]

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 but apparently it was 
> in the wrong place.  And I referenced this post 
> ,
>  
> 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.