Doug, I'm having a hard time understanding you. You are pointing at data
and coming to completely different conclusions than I do. Below you say,
"The Django cadre must regularly ask about the state of public sentiment
and satisfaction, because it is reckless to do otherwise." This is
after you examined the 3000 (!) responses to a survey of the Django
community. Is there some other way the Django team should ask about
public sentiment?
You also say, "If the consensus is to deny a need, the documentation
will continue to be an afterthought," after you yourself noticed that
the word "documentation" was a prominent answer to, "What's your
favorite thing about Django?" Seems like the public has been surveyed,
and they like the docs.
You've started a discussion here, and in response, people have come up
with concrete improvements to the docs, and are discussing other ideas.
But you still seem to be approaching this as if 1) the docs are widely
regarded as bad, and 2) nothing will be done about it.
Am I missing something?
--Ned.
On 1/1/16 5:35 PM, Doug Epling wrote:
I know some might have hoped I would just go away. But generally
speaking when I say I will do something I follow through. At the very
least I can work on the Glossary.
I looked at the poll of developers from last May. I loaded the results
in an R data.frame, but I did not find any relationships within that
data at all. I wonder what conclusions the core team was able to draw
from that other than, like, 77 percent of the responses came within 48
hours of its release. This fact must mean something,
Below is a wordcloud representation of the frequency of most used
words under the "What's your favorite thing about Django?" item.
This doesn't really mean a lot, but it is kind of neat to look at.
You can notice the prominance of 'documentation', and 'orm'.
Again, these probably don't mean a whole lot, although developer folks
sure exhibited an eagerness to express themselves. And you only need
to skim over those results to see that a lot of Django regulars, the
developers, really like the documentation. It would be interesting to
hear why or how these folks use documentation that causes them such
affinity for the docs.
Without those why-or-how answers to user interface questions, users
defined as extremely active members of the developer community, it is
hard to balance with the criticism that pops up here-and-there,
including my own.
This discussion begs to transpire among members of the core team
because nothing can change unless they see fit. If the consensus is to
deny a need, the documentation will continue to be an afterthought.
The Django core developers are not the only public involved. Some
might say they are in service to the public at large. The Django cadre
must regularly ask about the state of public sentiment and
satisfaction, because it is reckless to do otherwise.
Rplot_pos.png
On Sunday, December 27, 2015 at 5:42:49 PM UTC-5, Tim Graham wrote:
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/
<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/
<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 <https://code.djangoproject.com/ticket/25952>
but apparently it was in the wrong place. And I referenced
this post
<https://groups.google.com/forum/#%21searchin/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
<mailto:django-developers+unsubscr...@googlegroups.com>.
To post to this group, send email to
django-developers@googlegroups.com
<mailto: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/ffade33c-73c1-411a-8386-0c21fd842ace%40googlegroups.com
<https://groups.google.com/d/msgid/django-developers/ffade33c-73c1-411a-8386-0c21fd842ace%40googlegroups.com?utm_medium=email&utm_source=footer>.
For more options, visit https://groups.google.com/d/optout.
--
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/5687C1E3.3080000%40nedbatchelder.com.
For more options, visit https://groups.google.com/d/optout.
