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? 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 > 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 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 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 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. HTH, Shai.
