Hi again Doug, I'm leaving quotes in full here, as you requested, and to help demonstrate that it isn't useful at all. It is just "visual noise" that most readers will skip over.
On Sunday 27 December 2015 05:42:53 Doug Epling wrote: > 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. > An old Hebrew proverb says (paraphrased), before you call upon others to take out the pick between their teeth, take out the wooden beam between your eyes. I call you out on what seems like a contradiction in your writing, and instead of explaining it, you turn to general talk of criticism -- as if any criticism of your text is motivated by being personally hurt by it. Again: Please explain why, when you want to "read up" on a topic, a general explanation of that topic is not suitable. > > 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. > As opposed to responding only to things you pick-and-choose, taken out of context, while still quoting the parts you ignore -- which is what you're doing, when you pretend I didn't say that simple lists of attributes, as you asked for, are not there by design? > > > 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. > Wait, so it is good for you to bring up an example, but bad if someone else looks at it and shows that, at least in part, it does not exemplify what you claimed it did? > > 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: > No. This is not some goal you are trying to reach. Perhaps it is the way to reach some such goal. But it is still completely unclear what that goal is. A goal would be "making it easier to find information about a specific method", or "making it easier to understand how to achieve some task", or "making some text easier to read for a novice". > https://www.python.org/dev/peps/pep-0008/#comments > > in a block quote here: > > https://docs.djangoproject.com/en/1.9/internals/contributing/writing-docume > ntation/ > > with links to this: > > http://www.pearsonhighered.com/educator/product/Elements-of-Style-The/97802 > 05309023.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. > It means: Please refrain from telling us what needs to be done, until you've clearly explained what the problems are that you intend to solve, and for whom. Thanks for your interest in the project and the good will to improve it, Shai. > 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.
