Discussion:
structural & functional review of django documentation
(too old to reply)
Doug Epling
2015-12-18 23:35:03 UTC
Permalink
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+***@googlegroups.com.
To post to this group, send email to django-***@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/460b1aa4-bbb6-45e2-8619-0fb6d9af4f62%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Carl Meyer
2015-12-19 00:25:58 UTC
Permalink
Hi Doug,
Post by Doug Epling
I filed bug report
#25952 <https://code.djangoproject.com/ticket/25952>
but apparently it was in the wrong place.
In case it wasn't clear, it wasn't in the wrong place because it was
documentation-related, it was in the wrong place because Trac tickets
need to be focused and have clearly-bounded goals such that it's obvious
to everyone involved when the ticket has been solved and can be closed.
It doesn't work well for large-scale open-ended improvement efforts
(these should result in many Trac tickets, each one specific and concrete).
Post by Doug Epling
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?
Seems like the user's confusion in that django-users thread could be
addressed with a relatively simple patch to the contributing docs.
Perhaps you could make a pull request?
Post by Doug Epling
So I am hereby suggesting that the road map for the v. 2.0 release
include revamped documentation.
Thanks for taking the time to make the suggestion. Since Django is
developed by volunteers, there are basically two paths to making a
suggestion a reality:

1) Convince at least one of the existing volunteer contributors that
your suggestion is more important than the other improvements to Django
they are already working on. In this case, this will likely require more
hard evidence than you have provided so far that there is a serious
problem with the documentation that requires "revamping" them (as
opposed to iteratively improving them, which happens daily).

2) Spearhead the work yourself and clearly demonstrate its value in the
process.

I think that everyone here would gladly welcome whatever time you are
able to put into helping improve the docs.
Post by Doug Epling
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 certainly seems to me that data like this could be really useful in
deciding where to focus documentation improvements. It should be
possible to add such a feature to the online docs. I expect it would
require significant design and development work to put it in place,
which gets us back to options (1) and (2) above.

(By the way, this specific idea -- provide a feedback mechanism on the
online docs -- _is_ the sort of clearly-bounded task that would make a
good Trac ticket, though it might be best to see what feedback others
here have first.)
Post by Doug Epling
It might also be helpful to evaluate how different audiences access the
docs. Tutorials are great -- module and class libraries, not so much.
Are you saying this in general, or specifically in reference to the
Django docs?

If the latter, how specifically do you think the module and class
library documentation could be improved?
Post by Doug Epling
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?
2.0 is scheduled for release in December 2017. Between now and then
there will also be 1.10 and 1.11 releases, in Aug 2016 and Apr 2017
respectively, as outlined in
https://www.djangoproject.com/weblog/2015/jun/25/roadmap/

Carl
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/5674A416.8080103%40oddbird.net.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2015-12-26 19:08:58 UTC
Permalink
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.
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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.
Shai Berger
2015-12-26 20:56:32 UTC
Permalink
Hi Doug,
Post by Doug Epling
Thanks Carl --
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.
Post by Doug Epling
[...] But
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"""
Post by Doug Epling
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.
Doug Epling
2015-12-27 03:42:53 UTC
Permalink
Greetings Shai --
Post by Carl Meyer
Hi Doug,
Post by Doug Epling
Thanks Carl --
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.
Post by Carl Meyer
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.
Post by Doug Epling
[...] But
Just in general, it is unproductive to take things out-of-context, and
respond only to things you pick and choose.
Post by Carl Meyer
https://docs.djangoproject.com/en/1.9/search/?q=django.utils&release=1.9&pa
Post by Doug Epling
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
Post by Doug Epling
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!
Post by Carl Meyer
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.
Post by Carl Meyer
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
"""Utilities for writing code that runs on Python 2 and 3"""
Post by Doug Epling
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.
Post by Carl Meyer
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.
Post by Carl Meyer
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+***@googlegroups.com.
To post to this group, send email to django-***@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.
Shai Berger
2015-12-27 07:39:56 UTC
Permalink
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.
Post by Doug Epling
Greetings Shai --
Post by Carl Meyer
Hi Doug,
Post by Doug Epling
Thanks Carl --
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.
Post by Doug Epling
Post by Carl Meyer
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.
Post by Doug Epling
[...] 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?
Post by Doug Epling
Post by Carl Meyer
https://docs.djangoproject.com/en/1.9/search/?q=django.utils&release=1.9&
pa
Post by Doug Epling
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
Post by Doug Epling
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!
Post by Carl Meyer
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?
Post by Doug Epling
Post by Carl Meyer
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
"""Utilities for writing code that runs on Python 2 and 3"""
Post by Doug Epling
So is anyone convinced yet?
So, I'm not convinced. In particular, I don't understand the frame of mind
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".
Post by Doug Epling
https://www.python.org/dev/peps/pep-0008/#comments
https://docs.djangoproject.com/en/1.9/internals/contributing/writing-docume
ntation/
http://www.pearsonhighered.com/educator/product/Elements-of-Style-The/97802
05309023.page
https://www.python.org/dev/peps/pep-0008/
in the attribution.
Post by Carl Meyer
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.
Post by Doug Epling
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.
Post by Carl Meyer
HTH,
Shai.
Samuel Bishop
2015-12-27 08:44:06 UTC
Permalink
So I read the entire thread so far, and I saw some miscommunication induced
hostility. I wasn't sure what was miscommunicated, just progressively more
sure with each post that `something` had been miscommunicated.
So I read the ticket... and I can see why it was rejected.
Without at least some guidelines, rules, or procedures, a large community
driven project like Django would wind up with a bug tracker totally out of
hand.
If the desired outcomes I have inferred from what your writing, here and in
the ticket, are in fact what you hoped to achieve by creating the ticket,
then might be in agreement with you on 'this is something to fix'.
But I still think the wording you chose for the ticket, wasn't the right
way to describe it.

Django has exceptional "User" documentation. A developer building things
"with" Django, has high quality documentation on how to "use" Django. The
overarching goal is to make "using" Django as easy for a developer as we
can. Django has some good documentation on how to "begin" developing on the
source code that makes up Django.
It sounds like these are not the sort of documentation you are talking
about. Which might be where the miscommunication is starting.

Now, please correct me if I am wrong, but are you looking for a much more
'complete' set of 'internal' documentation so that you could for example
open the 'internal documentation' for Form and BaseForm for 1.8 and 1.9
side by side and see any differences in how things constructed 'under the
hood' ?
It was described already in this thread as "Javadoc-style" but I think that
missed the mark a bit.
Are you trying to suggest something more like the output of sphinx apidoc
(http://sphinx-doc.org/ext/autodoc.html#module-sphinx.ext.autodoc), where
docstrings, class and method invocation parameters, and optionally even
some of the inline comments inside a class or method, are assembled
together to give you a way to see some of the information about how these
pieces work, without going all the way to the level of detail you would
have if you read the source code itself?

I think there may be a concern that such information is covered in the
section of the documentation that covers changes between each version.
However I can also see the appeal of having the ability to view the
differences between any versions of the code, particularly if trying to
maintain or modernize an existing django based project or a reusable Django
application/library, I think this sort of thing is at least worthy of
discussion.

Regards
Sam
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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/c172d499-8d35-40bc-972e-7219e3f887bd%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Wim Feijen
2015-12-27 15:19:04 UTC
Permalink
Hi Doug,

I get lost regularly in Django's docs as well, so you are not alone there.

I think it is a good proposal to add:
"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 of the documentation.

I think it is a good thing to accumulate data. And if some page turns out
to be really bad or not helping, we have a choice to act on it.

For me, that would be a good ticket which I would definitely accept,
because the scope is small and clear and it is something we agree on. The
best way to proceed in my opinion is to create an new ticket, to keep it
clear. Do you want to create this ticket?

I have some other ideas on how to improve the documentation and layout as
well, but that is for another time.

Bye, Wim
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/39421256-8911-4fc7-800d-93d29a091d92%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Tim Graham
2015-12-27 15:41:56 UTC
Permalink
My main concern is that it will be non-trivial to setup that type of
feedback system, and I'm not sure how we would go about turning that type
of data into actionable tickets. If anyone has experience with such a
system, I'd be interested to hear about it.
Post by Carl Meyer
Hi Doug,
I get lost regularly in Django's docs as well, so you are not alone there.
"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 of the documentation.
I think it is a good thing to accumulate data. And if some page turns out
to be really bad or not helping, we have a choice to act on it.
For me, that would be a good ticket which I would definitely accept,
because the scope is small and clear and it is something we agree on. The
best way to proceed in my opinion is to create an new ticket, to keep it
clear. Do you want to create this ticket?
I have some other ideas on how to improve the documentation and layout as
well, but that is for another time.
Bye, Wim
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/5e3ad3cf-d822-455f-862e-12cedfe8bb5f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2015-12-27 19:47:35 UTC
Permalink
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?
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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/373526bb-be5e-4ca0-b5cb-2ae558c996b8%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Tim Graham
2015-12-27 22:42:49 UTC
Permalink
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/ (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/
Post by Doug Epling
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?
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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/c2bf1434-48f1-4bfb-8320-9ade8f6e8c0b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Aymeric Augustin
2015-12-28 13:48:08 UTC
Permalink
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.
I’ve been around for some time and, to be honest, I still have a hard time using this classification efficiently.
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?
This would help documentation writers at least as much as documentation readers. By providing guidelines for what kind of content should go where, it could help limit overlap between each type of document.
--
Aymeric.
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/DD6E5C59-85B4-482C-AC8D-03FCB3ECCB17%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.
Samuel Bishop
2015-12-28 17:40:13 UTC
Permalink
Broadly speaking, I think the 'optimal' goal is not going to be one that
changes our existing documentation structure in any disruptive way.

I think the general concept would be covered by either creating a "fourth
division". So we would go from "topics", "reference", and "how-to", to
"topics", "reference", "how-to", and "implementation"/"internals"/"APIs"/etc
Or enhancing the content in the reference section so that in addition to
our existing handwritten documentation, we expose the 'api-docs' tree as an
addendum to the reference section.

Sphinx gives us a lot of power to work with for trying either approach. I
cant remember which project I saw it on, but I recall seeing some sphinx
powered projects that had Django style hand written documentation, and each
heading (module, class, function, etc) in their hand written documentation
had an automatically generated link to the matcihng "implementation docs"
that took you to that segment of the sphinx autodoc output. It worked quite
well from what I recall.
I'm pretty busy for a few days, but if no one else does this first and
shares some results, I'll definitely take a look at the output from
sphinx's autodoc tools when run over the Django repo and post some
findings.
Since there is certainly the big question of "is the information we have
useful"?
The docstrings and sundry that sphinx uses for autodoc generation may need
work before it measures up to the quality standards of our existing hand
written documentation.
Post by Tim Graham
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
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/ (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/
Post by Doug Epling
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?
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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/25e03291-ccf4-4016-b95d-af994d3b725b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Tim Graham
2015-12-28 18:17:02 UTC
Permalink
There are some automatically added "[source]" links (see [1] for an
example), however, other links don't work (e.g. [2]) because we use the
convenience import path in the documentation. It would be a good task to
see if this could be fixed in Sphinx.

There is some room to add some "contributor facing" documentation to
"internals/" to describe the design of Django's components (e.g. an
accepted ticket for doing so for migrations [3]).

By the way, here's Jacob's series of blog posts that describes the
structure we have: https://jacobian.org/writing/great-documentation/

[1]
https://docs.djangoproject.com/en/dev/ref/exceptions/#django.core.exceptions.ObjectDoesNotExist
[2]
https://docs.djangoproject.com/en/dev/ref/applications/#django.apps.AppConfig
[3] https://code.djangoproject.com/ticket/24989
Post by Samuel Bishop
Broadly speaking, I think the 'optimal' goal is not going to be one that
changes our existing documentation structure in any disruptive way.
I think the general concept would be covered by either creating a "fourth
division". So we would go from "topics", "reference", and "how-to", to
"topics", "reference", "how-to", and "implementation"/"internals"/"APIs"/etc
Or enhancing the content in the reference section so that in addition to
our existing handwritten documentation, we expose the 'api-docs' tree as an
addendum to the reference section.
Sphinx gives us a lot of power to work with for trying either approach. I
cant remember which project I saw it on, but I recall seeing some sphinx
powered projects that had Django style hand written documentation, and each
heading (module, class, function, etc) in their hand written documentation
had an automatically generated link to the matcihng "implementation docs"
that took you to that segment of the sphinx autodoc output. It worked quite
well from what I recall.
I'm pretty busy for a few days, but if no one else does this first and
shares some results, I'll definitely take a look at the output from
sphinx's autodoc tools when run over the Django repo and post some
findings.
Since there is certainly the big question of "is the information we have
useful"?
The docstrings and sundry that sphinx uses for autodoc generation may need
work before it measures up to the quality standards of our existing hand
written documentation.
Post by Tim Graham
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
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/ (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/
Post by Doug Epling
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?
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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/60fb13c7-ace8-4e94-9de2-bb0d78b2c297%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Daniele Procida
2015-12-29 00:52:16 UTC
Permalink
Post by Samuel Bishop
I think the general concept would be covered by either creating a "fourth
division". So we would go from "topics", "reference", and "how-to", to
"topics", "reference", "how-to", and "implementation"/"internals"/"APIs"/etc
Or enhancing the content in the reference section so that in addition to
our existing handwritten documentation, we expose the 'api-docs' tree as an
addendum to the reference section.
The main existing sections are:

* tutorials (/intro)

Tutorials take the new user by the hand through a series of steps. The important thing isn't to explain all the steps, but to achieve something useful with a minimum of effort.

After every step of a tutorial, the user should have something that works, even if they barely understand what is happening (and it's not necessary for them to understand, that can come later. What matters is that they are successful).

* how-to guides (/howto)

How-to guides are recipes that take the user through steps in key subjects. They are more advanced than tutorials and assume a lot more about what the user already knows than tutorials do, and unlike documents in the tutorial they can stand alone.

* discussion and explanation (/topic)

Aimed at explaining (at a fairly high level) rather than doing.

* reference (/ref)

Technical reference for APIs, key models and so on. It doesn't need to explain so much as describe and instruct.


I don't know who came up with this structure in Django, but whoever did got it absolutely right.

The structure doesn't confuse teaching with explaining, and understands why tutorials should be concerned with concrete and particular rather than abstract and general matters. It understands the difference between explaning how to achieve something and explaining how something works. And so on.

I think that the structure of the documentation as much as its content is what makes it so good, but also that it's structure is obvious - so I am surprised that not everyone finds it so obvious. If that's the case then I agree it should be made more explicit.

Daniele
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/20151229005216.254922486%40mail.wservices.ch.
For more options, visit https://groups.google.com/d/optout.
Eric Holscher
2015-12-29 04:31:30 UTC
Permalink
Post by Daniele Procida
* tutorials (/intro)
Tutorials take the new user by the hand through a series of steps. The
important thing isn't to explain all the steps, but to achieve something
useful with a minimum of effort.
After every step of a tutorial, the user should have something that works,
even if they barely understand what is happening (and it's not necessary
for them to understand, that can come later. What matters is that they are
successful).
* how-to guides (/howto)
How-to guides are recipes that take the user through steps in key
subjects. They are more advanced than tutorials and assume a lot more about
what the user already knows than tutorials do, and unlike documents in the
tutorial they can stand alone.
* discussion and explanation (/topic)
Aimed at explaining (at a fairly high level) rather than doing.
* reference (/ref)
Technical reference for APIs, key models and so on. It doesn't need to
explain so much as describe and instruct.
I think the above post does a good job of describing the layout, and
something similar should be included in the docs. Without having read
Jacob's posts on the subject, there is nothing in the official docs that
gives the reader an understanding that this is how things are laid out, as
far as I know.

I think the underlying structure makes sense, and it seems that mostly
people are just upset about the lack of a pure auto-generated code
reference. I believe historically that this has been excluded explicitly,
not because of lack of technology. There is no use of autodoc in the Django
tree, even where it might make sense.

At Django Under the Hood this year, I had a few conversations with folks
about rethinking and explicitly defining these policies. I think it makes a
lot of sense to write down the logic and structure behind these decisions
in a DEP, and explain the layout to doc users in a few places in the
documentation explicitly.

Cheers,
Eric
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/0daa98a8-6714-4f76-adb2-ea5ced43d361%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Tim Graham
2015-12-29 16:25:39 UTC
Permalink
I've refined Daniele's explanation here:
https://github.com/django/django/pull/5888

Let me know if it helps and what could be better.
Post by Eric Holscher
Post by Daniele Procida
* tutorials (/intro)
Tutorials take the new user by the hand through a series of steps. The
important thing isn't to explain all the steps, but to achieve something
useful with a minimum of effort.
After every step of a tutorial, the user should have something that
works, even if they barely understand what is happening (and it's not
necessary for them to understand, that can come later. What matters is that
they are successful).
* how-to guides (/howto)
How-to guides are recipes that take the user through steps in key
subjects. They are more advanced than tutorials and assume a lot more about
what the user already knows than tutorials do, and unlike documents in the
tutorial they can stand alone.
* discussion and explanation (/topic)
Aimed at explaining (at a fairly high level) rather than doing.
* reference (/ref)
Technical reference for APIs, key models and so on. It doesn't need to
explain so much as describe and instruct.
I think the above post does a good job of describing the layout, and
something similar should be included in the docs. Without having read
Jacob's posts on the subject, there is nothing in the official docs that
gives the reader an understanding that this is how things are laid out, as
far as I know.
I think the underlying structure makes sense, and it seems that mostly
people are just upset about the lack of a pure auto-generated code
reference. I believe historically that this has been excluded explicitly,
not because of lack of technology. There is no use of autodoc in the Django
tree, even where it might make sense.
At Django Under the Hood this year, I had a few conversations with folks
about rethinking and explicitly defining these policies. I think it makes a
lot of sense to write down the logic and structure behind these decisions
in a DEP, and explain the layout to doc users in a few places in the
documentation explicitly.
Cheers,
Eric
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/9fa508d3-6dcc-4fd1-88c7-51845e0a00cb%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Tim Allen
2015-12-29 21:48:37 UTC
Permalink
Tim: that's definitely a big help, but still a click away. I'm just
brainstorming here, please bear with me!

I think part of my confusion as a newbie is from the front page itself,
at https://docs.djangoproject.com/

Now that I understand the concepts behind the documentation better (thanks
Daniele), it doesn't appear to be very well reflected on the front page.
There is a list of First steps, The model layer, and so on, but nothing in
the interface that clearly lets the user know that the documentation is
meant to be broken down into the "Tutorials / How-To / Explanation &
Discussion / Reference" paradigm. If that's what we are trying to
communicate, it should be shown to the user from the front of the
documentation clearly, IMHO.

A top-down, browsable hierarchy would have been extremely useful to me when
I was just getting started. The ToC has the kind of hierarchy I'm referring
to (https://docs.djangoproject.com/en/1.9/contents/), but comes across to
the user as a wall of text / links. Perhaps developing the ToC into a
navigation menu is worth some effort?

Does anyone else feel there is far too much on the front page? An
experienced Django dev will be more comfortable finding what they need
within the documentation, am I alone in thinking a much more simple front
page might be useful to the newcomer?

Regards,

Tim
Post by Tim Graham
https://github.com/django/django/pull/5888
Let me know if it helps and what could be better.
Post by Eric Holscher
Post by Daniele Procida
* tutorials (/intro)
Tutorials take the new user by the hand through a series of steps. The
important thing isn't to explain all the steps, but to achieve something
useful with a minimum of effort.
After every step of a tutorial, the user should have something that
works, even if they barely understand what is happening (and it's not
necessary for them to understand, that can come later. What matters is that
they are successful).
* how-to guides (/howto)
How-to guides are recipes that take the user through steps in key
subjects. They are more advanced than tutorials and assume a lot more about
what the user already knows than tutorials do, and unlike documents in the
tutorial they can stand alone.
* discussion and explanation (/topic)
Aimed at explaining (at a fairly high level) rather than doing.
* reference (/ref)
Technical reference for APIs, key models and so on. It doesn't need to
explain so much as describe and instruct.
I think the above post does a good job of describing the layout, and
something similar should be included in the docs. Without having read
Jacob's posts on the subject, there is nothing in the official docs that
gives the reader an understanding that this is how things are laid out, as
far as I know.
I think the underlying structure makes sense, and it seems that mostly
people are just upset about the lack of a pure auto-generated code
reference. I believe historically that this has been excluded explicitly,
not because of lack of technology. There is no use of autodoc in the Django
tree, even where it might make sense.
At Django Under the Hood this year, I had a few conversations with folks
about rethinking and explicitly defining these policies. I think it makes a
lot of sense to write down the logic and structure behind these decisions
in a DEP, and explain the layout to doc users in a few places in the
documentation explicitly.
Cheers,
Eric
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/12221065-6358-4a20-a383-60f3aac5f240%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Tim Graham
2015-12-29 22:17:31 UTC
Permalink
The docs I proposed would be added to the front page. I'm not sure if I
misunderstand what you meant by "still a click away"?

To me, the front page is a topical guide that links to all documentation
pages (topics/ref/howto) for each topic. I think it's useful, though I
don't really use it myself since I have most of the URLs in my history, so
I just rely on autocomplete to find the page I'm looking for. ;-)

Turning the table of contents page into a CSS menu sounds like a possibly
worthwhile task.

There is also an idea here for adding navigation breadcrumbs to the
documentation which might help:
https://github.com/django/djangoproject.com/issues/403
Post by Tim Allen
Tim: that's definitely a big help, but still a click away. I'm just
brainstorming here, please bear with me!
I think part of my confusion as a newbie is from the front page itself, at
https://docs.djangoproject.com/
Now that I understand the concepts behind the documentation better (thanks
Daniele), it doesn't appear to be very well reflected on the front page.
There is a list of First steps, The model layer, and so on, but nothing in
the interface that clearly lets the user know that the documentation is
meant to be broken down into the "Tutorials / How-To / Explanation &
Discussion / Reference" paradigm. If that's what we are trying to
communicate, it should be shown to the user from the front of the
documentation clearly, IMHO.
A top-down, browsable hierarchy would have been extremely useful to me
when I was just getting started. The ToC has the kind of hierarchy I'm
referring to (https://docs.djangoproject.com/en/1.9/contents/), but comes
across to the user as a wall of text / links. Perhaps developing the ToC
into a navigation menu is worth some effort?
Does anyone else feel there is far too much on the front page? An
experienced Django dev will be more comfortable finding what they need
within the documentation, am I alone in thinking a much more simple front
page might be useful to the newcomer?
Regards,
Tim
Post by Tim Graham
https://github.com/django/django/pull/5888
Let me know if it helps and what could be better.
Post by Eric Holscher
Post by Daniele Procida
* tutorials (/intro)
Tutorials take the new user by the hand through a series of steps. The
important thing isn't to explain all the steps, but to achieve something
useful with a minimum of effort.
After every step of a tutorial, the user should have something that
works, even if they barely understand what is happening (and it's not
necessary for them to understand, that can come later. What matters is that
they are successful).
* how-to guides (/howto)
How-to guides are recipes that take the user through steps in key
subjects. They are more advanced than tutorials and assume a lot more about
what the user already knows than tutorials do, and unlike documents in the
tutorial they can stand alone.
* discussion and explanation (/topic)
Aimed at explaining (at a fairly high level) rather than doing.
* reference (/ref)
Technical reference for APIs, key models and so on. It doesn't need to
explain so much as describe and instruct.
I think the above post does a good job of describing the layout, and
something similar should be included in the docs. Without having read
Jacob's posts on the subject, there is nothing in the official docs that
gives the reader an understanding that this is how things are laid out, as
far as I know.
I think the underlying structure makes sense, and it seems that mostly
people are just upset about the lack of a pure auto-generated code
reference. I believe historically that this has been excluded explicitly,
not because of lack of technology. There is no use of autodoc in the Django
tree, even where it might make sense.
At Django Under the Hood this year, I had a few conversations with folks
about rethinking and explicitly defining these policies. I think it makes a
lot of sense to write down the logic and structure behind these decisions
in a DEP, and explain the layout to doc users in a few places in the
documentation explicitly.
Cheers,
Eric
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/939e7dec-39cf-4605-919c-48dbe8692d2a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Eric Holscher
2015-12-30 05:34:28 UTC
Permalink
Post by Tim Graham
Turning the table of contents page into a CSS menu sounds like a possibly
worthwhile task.
There is also an idea here for adding navigation breadcrumbs to the
https://github.com/django/djangoproject.com/issues/403
Yea, I think the global TOC that the Read the Docs theme has is pretty good
at surfacing the structure of the
docs: http://docs.readthedocs.org/en/latest/ -- it allows users to see
where in the hierarchy they are, and what levels make sense.

That is already what is generating the TOC that is on the contents page, so
it would be pretty easy to include that in the sidebar for the docs (I
believe it's the `toc` variable in the Jinja template, but Django is using
the custom JSON backend, which works differently). I think Django's TOC is
quite large, so it would be hard to make it fit nicely into the sidebar,
but having the information available one each page would likely be useful
for UX. Perhaps you could at least do the top-level items, and an expanded
view of the current tree (the `collapse` option here
http://sphinx-doc.org/templating.html#toctree)
Post by Tim Graham
Post by Tim Allen
Tim: that's definitely a big help, but still a click away. I'm just
brainstorming here, please bear with me!
I think part of my confusion as a newbie is from the front page itself,
at https://docs.djangoproject.com/
Now that I understand the concepts behind the documentation better
(thanks Daniele), it doesn't appear to be very well reflected on the front
page. There is a list of First steps, The model layer, and so on, but
nothing in the interface that clearly lets the user know that the
documentation is meant to be broken down into the "Tutorials / How-To /
Explanation & Discussion / Reference" paradigm. If that's what we are
trying to communicate, it should be shown to the user from the front of the
documentation clearly, IMHO.
A top-down, browsable hierarchy would have been extremely useful to me
when I was just getting started. The ToC has the kind of hierarchy I'm
referring to (https://docs.djangoproject.com/en/1.9/contents/), but
comes across to the user as a wall of text / links. Perhaps developing the
ToC into a navigation menu is worth some effort?
Does anyone else feel there is far too much on the front page? An
experienced Django dev will be more comfortable finding what they need
within the documentation, am I alone in thinking a much more simple front
page might be useful to the newcomer?
Regards,
Tim
Post by Tim Graham
https://github.com/django/django/pull/5888
Let me know if it helps and what could be better.
Post by Eric Holscher
Post by Daniele Procida
* tutorials (/intro)
Tutorials take the new user by the hand through a series of steps. The
important thing isn't to explain all the steps, but to achieve something
useful with a minimum of effort.
After every step of a tutorial, the user should have something that
works, even if they barely understand what is happening (and it's not
necessary for them to understand, that can come later. What matters is that
they are successful).
* how-to guides (/howto)
How-to guides are recipes that take the user through steps in key
subjects. They are more advanced than tutorials and assume a lot more about
what the user already knows than tutorials do, and unlike documents in the
tutorial they can stand alone.
* discussion and explanation (/topic)
Aimed at explaining (at a fairly high level) rather than doing.
* reference (/ref)
Technical reference for APIs, key models and so on. It doesn't need to
explain so much as describe and instruct.
I think the above post does a good job of describing the layout, and
something similar should be included in the docs. Without having read
Jacob's posts on the subject, there is nothing in the official docs that
gives the reader an understanding that this is how things are laid out, as
far as I know.
I think the underlying structure makes sense, and it seems that mostly
people are just upset about the lack of a pure auto-generated code
reference. I believe historically that this has been excluded explicitly,
not because of lack of technology. There is no use of autodoc in the Django
tree, even where it might make sense.
At Django Under the Hood this year, I had a few conversations with
folks about rethinking and explicitly defining these policies. I think it
makes a lot of sense to write down the logic and structure behind these
decisions in a DEP, and explain the layout to doc users in a few places in
the documentation explicitly.
Cheers,
Eric
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/ae56e326-1de9-4c28-919f-92e6b62caa41%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2016-01-01 22:35:58 UTC
Permalink
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.

[image: Rplot_pos.png]
Post by Tim Graham
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
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/ (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/
Post by Doug Epling
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?
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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.
For more options, visit https://groups.google.com/d/optout.
Tim Graham
2016-01-01 23:19:05 UTC
Permalink
There weren't any secret discussions among the core team about the data
from the survey. It helped to inform the roadmap as far as how often a
Django release should happen, where 6 and 12 months were the most popular
answers, and we decided on 8 months as a compromise between the two (all of
this discussion is on this mailing list). Other than that, I don't know
that it's translated in any actionable results.

I'm happy to support you if you have some specific next steps in mind.
Post by Doug Epling
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.
[image: Rplot_pos.png]
Post by Tim Graham
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
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/ (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/
Post by Doug Epling
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?
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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/da87dca8-89a7-4cf7-9ee7-e650ad893e45%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2016-01-02 04:48:24 UTC
Permalink
Hey Tim --

Basically, we need data. My recommendation involves two separate initiatives.

First is, has been, a discussion open for spectators but limited participants to core members. Asside from its subject pertaining current state and future path, all other details are above my pay grade.

Second is, has been, the active solicitation of a standardized body of feedback from the peripheral users of Django documentation in a fairly substantial amount. We might want to start a new discussion thread on this particular topic.

Many thanks for your hard work and dedication.
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/d9f4aa9a-1d9c-4b8b-8e2b-b6c9427b4ce1%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Aymeric Augustin
2016-01-02 09:50:28 UTC
Permalink
Post by Doug Epling
First is, has been, a discussion open for spectators but limited participants to core members. Asside from its subject pertaining current state and future path, all other details are above my pay grade.
Hi Doug,

I’m afraid there’s a misunderstanding of how this community operates.

"Team members” — we de-emphazised the “core dev” terminology in 2014 because it over-valued writing code — are people who have made consistent, constructive contributions to Django, usually starting small and then moving on to more ambitious projects. Albeit slow, this process is the best way we have found for new contributors to gain trust from existing contributors.

There needs to be some mechanism to give a consistent direction to the Django project. Currently we have two layers of decision: community consensus and technical board arbitration vote. Obviously voices of team members matter more in community discussions. We hope that’s because of their experience with Django and the quality of what they say, not just because they carry a “team member” flag. Arbitration votes almost never happen. (There was only one, ever, to drop support for IE8 from the admin.)

In practice, team members tend to have busy professional lives outside of Django. This has stalled many projects in the past. For this reason we structured our organization in order to empower community members as much as possible and to require as little input from the Django team as possible.

We wouldn’t find a core-only conversation nearly as useful as a community-wide discussion. Perhaps that’s why core panels have fallen out of fashion at DjangoCons during the last couple of years. And we definitely don’t want contributors to censor themselves because of perceived pay grade.

The only pre-requisite to tackling massive projects such as “let’s restructure the whole documentation” is to have built enough trust from the current team for everyone to know that you will complete it in good conditions. Building that trust requires completing successfully small projects, then increasingly large ones. Team membership may be offered at some point in that process.

I hope this helps,
--
Aymeric.
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/2C085DD1-0F56-4ABF-91C7-A3E4D96E345D%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2016-01-04 01:52:10 UTC
Permalink
Hello Aymeric --

Yes indeed, I misunderstood. Thank you for lining things out for me.
Loosely, the group I am talking about is the group of a couple thousand who
completed that survey in the first 48 hours. It would be great to know why
a lot of those ~2000 folks feel so stongly and positive about the
documentation. I don't know how to organize this. With all due respect, I
was hoping the mechanism you outlined could kick-in to facillitate this.

As for other thread in my proposal, the way I would approach this would be
on a foundation of the mass media research of Phillip Palmgreen with 'uses
and gratification' theory which is rooted deeply in Fishbein's
'expectancy-value' theory with perhaps some Charles Osgood thrown in for
good measure. All this stuff is from the eighty's -- possibly somewhat
out-of-date. So, you are a mathematician, huh? How are your statistics?

And this might be some kind of non sequitur, but in any case, I looked at
the text files from GitHub that comprise our published documentation. I am
attaching two files. One is a list of words used 50 or more times. I
don't know how words like 'youll' made it in there, but a lot of these
words are good candidates for the Glossary. Also, enclosed is another file
listing the file sources for these words.

Thanks again,
Post by Doug Epling
Post by Doug Epling
First is, has been, a discussion open for spectators but limited
participants to core members. Asside from its subject pertaining current
state and future path, all other details are above my pay grade.
Hi Doug,
I’m afraid there’s a misunderstanding of how this community operates.
"Team members” — we de-emphazised the “core dev” terminology in 2014
because it over-valued writing code — are people who have made consistent,
constructive contributions to Django, usually starting small and then
moving on to more ambitious projects. Albeit slow, this process is the best
way we have found for new contributors to gain trust from existing
contributors.
There needs to be some mechanism to give a consistent direction to the
Django project. Currently we have two layers of decision: community
consensus and technical board arbitration vote. Obviously voices of team
members matter more in community discussions. We hope that’s because of
their experience with Django and the quality of what they say, not just
because they carry a “team member” flag. Arbitration votes almost never
happen. (There was only one, ever, to drop support for IE8 from the admin.)
In practice, team members tend to have busy professional lives outside of
Django. This has stalled many projects in the past. For this reason we
structured our organization in order to empower community members as much
as possible and to require as little input from the Django team as
possible.
We wouldn’t find a core-only conversation nearly as useful as a
community-wide discussion. Perhaps that’s why core panels have fallen out
of fashion at DjangoCons during the last couple of years. And we definitely
don’t want contributors to censor themselves because of perceived pay
grade.
The only pre-requisite to tackling massive projects such as “let’s
restructure the whole documentation” is to have built enough trust from the
current team for everyone to know that you will complete it in good
conditions. Building that trust requires completing successfully small
projects, then increasingly large ones. Team membership may be offered at
some point in that process.
I hope this helps,
--
Aymeric.
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/676fbf93-acee-4c23-8444-a4c2d93b0ca3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2016-01-04 01:59:23 UTC
Permalink
Hello Aymeric --

Yes indeed, I misunderstood. Thank you for lining things out for me.
Loosely, the group I am talking about is the group of a couple thousand who
completed that survey in the first 48 hours. It would be great to know why
a lot of those ~2000 folks feel so stongly and positive about the
documentation. I don't know how to organize this. With all due respect, I
was hoping the mechanism you outlined could kick-in to facillitate this.

As for other thread in my proposal
<https://en.wikipedia.org/wiki/User_analysis>, the way I would approach
this would be on a foundation of the mass media research of Phillip
Palmgreen with 'uses and gratification' theory which is rooted deeply in
Fishbein's 'expectancy-value' theory with perhaps some Charles Osgood
thrown in for good measure. All this stuff is from the eighty's --
possibly somewhat out-of-date. So, you are a mathematician, huh? How are
your statistics?

And this might be some kind of non sequitur, but in any case, I looked at
the text files from GitHub that comprise our published documentation. I am
attaching two files. One is a list of words used 50 or more times. I
don't know how words like 'youll' made it in there, but a lot of these
words are good candidates for the Glossary. Also, enclosed is another file
listing the file sources for these words.

Thanks again,
Post by Doug Epling
Post by Doug Epling
First is, has been, a discussion open for spectators but limited
participants to core members. Asside from its subject pertaining current
state and future path, all other details are above my pay grade.
Hi Doug,
I’m afraid there’s a misunderstanding of how this community operates.
"Team members” — we de-emphazised the “core dev” terminology in 2014
because it over-valued writing code — are people who have made consistent,
constructive contributions to Django, usually starting small and then
moving on to more ambitious projects. Albeit slow, this process is the best
way we have found for new contributors to gain trust from existing
contributors.
There needs to be some mechanism to give a consistent direction to the
Django project. Currently we have two layers of decision: community
consensus and technical board arbitration vote. Obviously voices of team
members matter more in community discussions. We hope that’s because of
their experience with Django and the quality of what they say, not just
because they carry a “team member” flag. Arbitration votes almost never
happen. (There was only one, ever, to drop support for IE8 from the admin.)
In practice, team members tend to have busy professional lives outside of
Django. This has stalled many projects in the past. For this reason we
structured our organization in order to empower community members as much
as possible and to require as little input from the Django team as
possible.
We wouldn’t find a core-only conversation nearly as useful as a
community-wide discussion. Perhaps that’s why core panels have fallen out
of fashion at DjangoCons during the last couple of years. And we definitely
don’t want contributors to censor themselves because of perceived pay
grade.
The only pre-requisite to tackling massive projects such as “let’s
restructure the whole documentation” is to have built enough trust from the
current team for everyone to know that you will complete it in good
conditions. Building that trust requires completing successfully small
projects, then increasingly large ones. Team membership may be offered at
some point in that process.
I hope this helps,
--
Aymeric.
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/00f54342-b056-4b8d-8165-c921777cc11d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2016-07-14 15:23:26 UTC
Permalink
Post by Doug Epling
Hey Tim --
Basically, we need data. My recommendation involves two separate initiatives.
First is, has been, a discussion open for spectators but limited
participants to core members. Asside from its subject pertaining current
state and future path, all other details are above my pay grade.
Actually, whatever on that first point.

But on this second point it entirely not necessary. Django has all the
feedback in textual form that it would ever need for some user analysis. I
did not realize the extent of the IRC logs. This body of text is a
treasure chest. And Django should be mining it for all it is worth.
Post by Doug Epling
Second is, has been, the active solicitation of a standardized body of
feedback from the peripheral users of Django documentation in a fairly
substantial amount. We might want to start a new discussion thread on this
particular topic.
Many thanks for your hard work and dedication.
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/facc1359-7ec6-4683-b5f4-eeeabbc29e20%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Ned Batchelder
2016-01-02 12:26:11 UTC
Permalink
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.
Post by Doug Epling
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
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
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/>
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?
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
To post to this group, send email to
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+***@googlegroups.com.
To post to this group, send email to django-***@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.
Doug Epling
2016-01-04 03:59:29 UTC
Permalink
Hi Ned --

That is an excellent point! There was some back-and-forth about bread crumbs. It would be awesome if we not only implemented that, but used it to track user's progress through the docs, and collect this info.

Thanks,
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/da51873a-7606-4c69-8788-c3e97471ce17%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Scot Hacker
2016-01-04 07:45:56 UTC
Permalink
The written quality of the Django docs has been a selling point for years,
but discoverability has never been great. I wanted to add two notes:

1) The front page of the docs says docs are organized into four sections
(Tutorials, Topic Guides, Reference Guides, How-To Guides). And it's been
proposed that we add a fifth docstring-generated API Reference as well. But
remember that most people looking to solve a problem under deadline start
with search, not taxonomy. Search results do *seem* to be labeled with the
section of the docs they come from, but the sections referenced don't
actually correspond to the four sections we say use! If I search for
"forms" I get results that claim to come from "API Reference," "Using
Django," "Release Notes," which don't match the names of our four sections.
I propose that A) search results clearly indicate the doc sections that we
claim we use for organization; B) Search results be grouped by type (e.g.
show all results from Using Django first, followed by all results from API
Reference)... or whatever. Or a user could use checkboxes to select which
section of the docs they want to search. Or faceted search results so users
can quickly toggle or filter the sources of the search results? There are a
lot of ways to solve this - just pointing out that our search experiences
could be sharper and more customizable.

2) I've encountered a number of situations where search didn't help because
I didn't yet know enough to search for the right thing. I remember early in
my Django experience trying to figure out how to have a "global variable"
for my project and that search string not turning up what I needed to
know... because what I really should have been searching for was "context
processors".* I think we could make strides in search-ability through the
indication of a tagging system. Tags could either be controlled through
commits, or dynamic (users could tag topics on the fly, and a weighting
system would apply to search results).

* Even today, searching the docs for "context processor" does not take me
quickly to a clean example of how to implement a context processor - I
really have to dig for this information.

./s
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/da7ae84d-7696-4705-b8a3-115c9ec40b94%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2016-01-05 00:14:56 UTC
Permalink
Hi Scot --

Search terms would be another really great source of information.
collecting these and somehow relating them to user's ensuing journey
through the documentation could be very helpful.

thanks,
Post by Scot Hacker
The written quality of the Django docs has been a selling point for years,
1) The front page of the docs says docs are organized into four sections
(Tutorials, Topic Guides, Reference Guides, How-To Guides). And it's been
proposed that we add a fifth docstring-generated API Reference as well. But
remember that most people looking to solve a problem under deadline start
with search, not taxonomy. Search results do *seem* to be labeled with the
section of the docs they come from, but the sections referenced don't
actually correspond to the four sections we say use! If I search for
"forms" I get results that claim to come from "API Reference," "Using
Django," "Release Notes," which don't match the names of our four sections.
I propose that A) search results clearly indicate the doc sections that we
claim we use for organization; B) Search results be grouped by type (e.g.
show all results from Using Django first, followed by all results from API
Reference)... or whatever. Or a user could use checkboxes to select which
section of the docs they want to search. Or faceted search results so users
can quickly toggle or filter the sources of the search results? There are a
lot of ways to solve this - just pointing out that our search experiences
could be sharper and more customizable.
2) I've encountered a number of situations where search didn't help
because I didn't yet know enough to search for the right thing. I remember
early in my Django experience trying to figure out how to have a "global
variable" for my project and that search string not turning up what I
needed to know... because what I really should have been searching for was
"context processors".* I think we could make strides in search-ability
through the indication of a tagging system. Tags could either be controlled
through commits, or dynamic (users could tag topics on the fly, and a
weighting system would apply to search results).
* Even today, searching the docs for "context processor" does not take me
quickly to a clean example of how to implement a context processor - I
really have to dig for this information.
./s
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/f772dd19-967b-48a5-9926-9bf723b698a3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Tim Allen
2016-01-05 15:10:00 UTC
Permalink
Scot, you've summarized what I've run into as well beautifully. My problem
has never been with the documentation once I find it - it has been the path
to finding it. Another frustration is trying to find a part of the
documentation I know I've seen before a second time. I seem to go round and
round in link circles for a frustrating amount of time. Taxonomy here is
important, because of the frequent use and reuse of potential search terms
throughout the documentation.

Regards,

Tim
Post by Scot Hacker
The written quality of the Django docs has been a selling point for years,
1) The front page of the docs says docs are organized into four sections
(Tutorials, Topic Guides, Reference Guides, How-To Guides). And it's been
proposed that we add a fifth docstring-generated API Reference as well. But
remember that most people looking to solve a problem under deadline start
with search, not taxonomy. Search results do *seem* to be labeled with the
section of the docs they come from, but the sections referenced don't
actually correspond to the four sections we say use! If I search for
"forms" I get results that claim to come from "API Reference," "Using
Django," "Release Notes," which don't match the names of our four sections.
I propose that A) search results clearly indicate the doc sections that we
claim we use for organization; B) Search results be grouped by type (e.g.
show all results from Using Django first, followed by all results from API
Reference)... or whatever. Or a user could use checkboxes to select which
section of the docs they want to search. Or faceted search results so users
can quickly toggle or filter the sources of the search results? There are a
lot of ways to solve this - just pointing out that our search experiences
could be sharper and more customizable.
2) I've encountered a number of situations where search didn't help
because I didn't yet know enough to search for the right thing. I remember
early in my Django experience trying to figure out how to have a "global
variable" for my project and that search string not turning up what I
needed to know... because what I really should have been searching for was
"context processors".* I think we could make strides in search-ability
through the indication of a tagging system. Tags could either be controlled
through commits, or dynamic (users could tag topics on the fly, and a
weighting system would apply to search results).
* Even today, searching the docs for "context processor" does not take me
quickly to a clean example of how to implement a context processor - I
really have to dig for this information.
./s
--
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+***@googlegroups.com.
To post to this group, send email to django-***@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/b0f50682-2c4b-42f8-a4b9-33fc3121f315%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Doug Epling
2015-12-28 02:06:46 UTC
Permalink
Tim --

Thank you so much for the link to that blog post. I am going away now to
think about that data a little, but I'll be back.

I was not aware of the "topics", "reference", and "how-to" assortment. But
I have scanned the Table of Contents, and I find almost nothing here
addressing documentation <https://docs.djangoproject.com/en/1.9/internals/>.


I am afraid I have caused enough trouble for now. I need a little time to
digest that survey data, but I will be back.

When I look at Django docs, I want to be informed as a Python programmer,
perhaps even a novice one. As far as I can tell, there is no such thing in
Django as Forms -- forms or form either for this matter. There is a Form
class, and it can instantiate any number of objects. But THIS KIND OF
THING (caps for emphasis on this example) is the kernel of my frustration.

Again, many thanks Tim, your last post is very helpful to me.
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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/627694e7-502e-4b1e-9c6b-b7bd78da8653%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Tim Allen
2015-12-28 10:44:48 UTC
Permalink
HI Doug, I can relate to what you are saying, I had a similar experience
when trying to find a reference for the generic FormView. Issuing a P.R. to
improve it is on my BLOTTD (big list of things to do). I was interviewing a
candidate last week who knows I'm a big fan of Django, and wanted to throw
a curveball, so I asked what they thought the biggest shortcoming of Django
is. Without hesitation, they mentioned that their current team (which is
just starting to learn Django) had trouble with the documentation. When I
followed up, they mentioned it all seemed to be by example, rather than
reference, and both are useful.

It is a big fish to fry, as Tim G mentioned, but I think it can be improved
incrementally. I've used the Django Documentation for several years, and
this is the first I've heard of the "topics", "reference" and "how-to".

As someone who used PHP for years, one thing I always felt they got right
was documentation. That may just be the way my mind works, however.

This is a long way of saying, I'm interesting in helping out.

Regards,

Tim
Post by Doug Epling
Tim --
Thank you so much for the link to that blog post. I am going away now to
think about that data a little, but I'll be back.
I was not aware of the "topics", "reference", and "how-to" assortment.
But I have scanned the Table of Contents, and I find almost nothing here
addressing documentation
<https://docs.djangoproject.com/en/1.9/internals/>.
I am afraid I have caused enough trouble for now. I need a little time to
digest that survey data, but I will be back.
When I look at Django docs, I want to be informed as a Python programmer,
perhaps even a novice one. As far as I can tell, there is no such thing in
Django as Forms -- forms or form either for this matter. There is a Form
class, and it can instantiate any number of objects. But THIS KIND OF
THING (caps for emphasis on this example) is the kernel of my frustration.
Again, many thanks Tim, your last post is very helpful to me.
Post by Doug Epling
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+***@googlegroups.com.
To post to this group, send email to django-***@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/025ed576-59e1-45cf-9cbe-be11ee56115d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Loading...