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 I go here: https://docs.djangoproject.com/en/1.9/ref/forms/ This page is the Joy of Cooking with Django, I figure I am in the wrong place so follow a link to here: https://docs.djangoproject.com/en/1.9/topics/forms/ No, this isn't what I am looking for, this is the intro; so I open a text editor and the forms.py module. And I skim through the code and documentation. Largely, I feel like the functions are addressing me because there are many, many sentence fragments composed of predicate portions of sentences in violation of PEP 0008. It would be easy to pick out at least one run-on sentence as well. Then I get to the bottom of this document in my text editor, and I find the Form class. There is some mumbo-jumbo there that attempts to provide clarity by providing cute. And I wonder WTF are these parameters? So I scroll back to the top of this page in my text editor, and things become somewhat apparent. 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&page=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. So is anyone convinced yet? Like you said, Carl, I need to persuade at least one person. So if there is anyone else in the community who was drawn to django because of its journalistic roots, like me, or who has degrees in both journalism and computer science, like me, or who just fancies his/her self as a wordsmith and has an affinity for python, like me, please feel free to join in this conversation. Otherwise, everyone can just go on thinking I am just grousing over nothing important. On Friday, December 18, 2015 at 7:02:56 PM UTC-5, 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/6e2c945f-524d-4504-802f-3df009c8244b%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
