Greetings Shai -- On Saturday, December 26, 2015 at 3:57:00 PM UTC-5, Shai Berger wrote: > > Hi Doug, > > On Saturday 26 December 2015 21:08:58 Doug Epling wrote: > > Thanks Carl -- > > > > Here is a good example: > > > > I wanted to read-up on the Form class. First thing I did was go here: > > > > https://docs.djangoproject.com/en/1.9/search/?q=Form > > > > yadda, yadda, yadda, recipe, recipe, .... where is the simple list of > > attributes contained in this class? > > > > So, this already seems odd. You want to read up on it, but you're not > actually > interested in what people wrote up on it? >
I am sorry if someone's carefully crafted 'how-to`s' got stepped-on by my criticism, really, criticism stings. But this does not make the criticism invalid. In fact, good writers should relish the sting of criticism because it makes them better. > > It sounds like you're looking for a Javadoc-style reference. I always had > the > feelng that Django avoided these by design; a "simple list of attributes" > is > usually not helpful for a human who wants to get something done. > > > [...] But Just in general, it is unproductive to take things out-of-context, and respond only to things you pick and choose. > > > what-the-heck is this 'six' we import from django.util? So I go here: > > > > > https://docs.djangoproject.com/en/1.9/search/?q=django.utils&release=1.9&pa > > ge=1 > > > > Here I reach a dead end. I could go farther, but this is all a > > side-track. This isn't even relevant to what I am working on. And it > is > > entirely possible 'six' is something I should just know about and don't. > > > > It is something you should either know about, or not care about. As far as > Au contraire, mon frere! > forms are concerned, it is just an implementation detail. So if you're > looking > to use forms, you should probably not care about it. If you're looking to > hack > Please try to stay on topic. The topic is documentation. The excursion into the Form class, specifically, was only exemplary. > on forms, the issue of Python 2/3 compatibility (which six is a solution > for) > should be familiar to you; and if it isn't, and you're already reading > source > files, you just might open the six.py module, where you'll find a > docstring > which reads: > > """Utilities for writing code that runs on Python 2 and 3""" > > > So is anyone convinced yet? > > So, I'm not convinced. In particular, I don't understand the frame of mind My frame of mind is that we should put the entire text of this section: https://www.python.org/dev/peps/pep-0008/#comments in a block quote here: https://docs.djangoproject.com/en/1.9/internals/contributing/writing-documentation/ with links to this: http://www.pearsonhighered.com/educator/product/Elements-of-Style-The/9780205309023.page and a link to this: https://www.python.org/dev/peps/pep-0008/ in the attribution. > that would lead you along the journey you described. You said you wanted > to > "read up on forms", but that sounds like a means, not a goal; I think it > would > help to clear up the difficulties you ran into and the improvements you > wish to > introduce, if you describe the goals you wish the documentation to serve. > > I have seen "design games" based on "personas" -- where you want to write > specs for a system, and you portray the prospective users. You give them > names, ages, jobs, some basic life-story, and a main goal for using the > system, and then when you consider design decision you can say "oh, that > would > please Ned to no end", or, "Catelyn wouldn't like that". I think such a > game > may be helpful for clarifying -- to yourself and to others -- what exactly > are > the problems you're trying to solve. > I have no idea what that means. P.S. This along with my prior suggestions to start collecting A) user input, and B) potential use-cases from developers/experts. Many thanks, Shai, for your input. > > HTH, > Shai. > -- 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/566faeb6-a679-4e9a-8278-c0eeeff77e0e%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
