structural & functional review of django documentation
498 views
Skip to first unread message
Doug Epling
Dec 18, 2015, 7:02:56 PM12/18/15
to Django developers (Contributions to Django itself)
I filed bug report
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?
#25952
but apparently it was in the wrong place. And I referenced this post, 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?
Carl Meyer
Dec 18, 2015, 7:26:20 PM12/18/15
to django-d...@googlegroups.com
Hi Doug,
On 12/18/2015 04:35 PM, Doug Epling wrote:
> I filed bug report
>
> #25952 <https://code.djangoproject.com/ticket/25952>
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).
> And I referenced this post
> <https://groups.google.com/forum/#!searchin/django-users/documentation/django-users/1qHviCZMPJA/_8qVb0YYdhAJ>,
addressed with a relatively simple patch to the contributing docs.
Perhaps you could make a pull request?
> 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.
> 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.)
> 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?
> 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
On 12/18/2015 04:35 PM, Doug Epling wrote:
> I filed bug report
>
>
> but apparently it was in the wrong place.
In case it wasn't clear, it wasn't in the wrong place because it was
> but apparently it was in the wrong place.
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).
> 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?
> So I am hereby suggesting that the road map for the v. 2.0 release
> include revamped documentation.
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.
> 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.
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.)
> It might also be helpful to evaluate how different audiences access the
> docs. Tutorials are great -- module and class libraries, not so much.
Django docs?
If the latter, how specifically do you think the module and class
library documentation could be improved?
> 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?
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
Doug Epling
Dec 26, 2015, 2:08:59 PM12/26/15
to Django developers (Contributions to Django itself)
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.
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.
Shai Berger
Dec 26, 2015, 3:57:00 PM12/26/15
to django-d...@googlegroups.com
Hi Doug,
On Saturday 26 December 2015 21:08:58 Doug Epling wrote:
> Thanks Carl --
>
> Here is a good example:
>
> I wanted to read-up on the Form class. First thing I did was go here:
>
> https://docs.djangoproject.com/en/1.9/search/?q=Form
>
> yadda, yadda, yadda, recipe, recipe, .... where is the simple list of
> attributes contained in this class?
>
So, this already seems odd. You want to read up on it, but you're not actually
interested in what people wrote up on it?
It sounds like you're looking for a Javadoc-style reference. I always had the
feelng that Django avoided these by design; a "simple list of attributes" is
usually not helpful for a human who wants to get something done.
> [...] But
forms are concerned, it is just an implementation detail. So if you're looking
to use forms, you should probably not care about it. If you're looking to hack
on forms, the issue of Python 2/3 compatibility (which six is a solution for)
should be familiar to you; and if it isn't, and you're already reading source
files, you just might open the six.py module, where you'll find a docstring
which reads:
"""Utilities for writing code that runs on Python 2 and 3"""
> So is anyone convinced yet?
So, I'm not convinced. In particular, I don't understand the frame of mind
that would lead you along the journey you described. You said you wanted to
"read up on forms", but that sounds like a means, not a goal; I think it would
help to clear up the difficulties you ran into and the improvements you wish to
introduce, if you describe the goals you wish the documentation to serve.
I have seen "design games" based on "personas" -- where you want to write
specs for a system, and you portray the prospective users. You give them
names, ages, jobs, some basic life-story, and a main goal for using the
system, and then when you consider design decision you can say "oh, that would
please Ned to no end", or, "Catelyn wouldn't like that". I think such a game
may be helpful for clarifying -- to yourself and to others -- what exactly are
the problems you're trying to solve.
HTH,
Shai.
On Saturday 26 December 2015 21:08:58 Doug Epling wrote:
> Thanks Carl --
>
> Here is a good example:
>
> I wanted to read-up on the Form class. First thing I did was go here:
>
> https://docs.djangoproject.com/en/1.9/search/?q=Form
>
> yadda, yadda, yadda, recipe, recipe, .... where is the simple list of
> attributes contained in this class?
>
interested in what people wrote up on it?
It sounds like you're looking for a Javadoc-style reference. I always had the
feelng that Django avoided these by design; a "simple list of attributes" is
usually not helpful for a human who wants to get something done.
> [...] But
> what-the-heck is this 'six' we import from django.util? So I go here:
>
> https://docs.djangoproject.com/en/1.9/search/?q=django.utils&release=1.9&pa
> ge=1
>
> Here I reach a dead end. I could go farther, but this is all a
> side-track. This isn't even relevant to what I am working on. And it is
> entirely possible 'six' is something I should just know about and don't.
>
It is something you should either know about, or not care about. As far as
>
> 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.
>
forms are concerned, it is just an implementation detail. So if you're looking
to use forms, you should probably not care about it. If you're looking to hack
on forms, the issue of Python 2/3 compatibility (which six is a solution for)
should be familiar to you; and if it isn't, and you're already reading source
files, you just might open the six.py module, where you'll find a docstring
which reads:
"""Utilities for writing code that runs on Python 2 and 3"""
> So is anyone convinced yet?
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
Dec 26, 2015, 10:42:53 PM12/26/15
to Django developers (Contributions to Django itself)
Greetings Shai --
On Saturday, December 26, 2015 at 3:57:00 PM UTC-5, Shai Berger wrote:
Hi Doug,
On Saturday 26 December 2015 21:08:58 Doug Epling wrote:
> Thanks Carl --
>
> Here is a good example:
>
> I wanted to read-up on the Form class. First thing I did was go here:
>
> https://docs.djangoproject.com/en/1.9/search/?q=Form
>
> yadda, yadda, yadda, recipe, recipe, .... where is the simple list of
> attributes contained in this class?
>
So, this already seems odd. You want to read up on it, but you're not actually
interested in what people wrote up on it?
I am sorry if someone's carefully crafted 'how-to`s' got stepped-on by my criticism, really, criticism stings. But this does not make the criticism invalid. In fact, good writers should relish the sting of criticism because it makes them better.
It sounds like you're looking for a Javadoc-style reference. I always had the
feelng that Django avoided these by design; a "simple list of attributes" is
usually not helpful for a human who wants to get something done.
> [...] But
Just in general, it is unproductive to take things out-of-context, and respond only to things you pick and choose.
> what-the-heck is this 'six' we import from django.util? So I go here:
>
> https://docs.djangoproject.com/en/1.9/search/?q=django.utils&release=1.9&pa
> ge=1
>
> Here I reach a dead end. I could go farther, but this is all a
> side-track. This isn't even relevant to what I am working on. And it is
> entirely possible 'six' is something I should just know about and don't.
>
It is something you should either know about, or not care about. As far as
Au contraire, mon frere!
forms are concerned, it is just an implementation detail. So if you're looking
to use forms, you should probably not care about it. If you're looking to hack
Please try to stay on topic. The topic is documentation. The excursion into the Form class, specifically, was only exemplary.
on forms, the issue of Python 2/3 compatibility (which six is a solution for)
should be familiar to you; and if it isn't, and you're already reading source
files, you just might open the six.py module, where you'll find a docstring
which reads:
"""Utilities for writing code that runs on Python 2 and 3"""
> So is anyone convinced yet?
So, I'm not convinced. In particular, I don't understand the frame of mind
My frame of mind is that we should put the entire text of this section:
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.
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.
HTH,
Shai.
Shai Berger
Dec 27, 2015, 2:40:25 AM12/27/15
to django-d...@googlegroups.com
Hi again Doug,
I'm leaving quotes in full here, as you requested, and to help demonstrate
that it isn't useful at all. It is just "visual noise" that most readers will
skip over.
On Sunday 27 December 2015 05:42:53 Doug Epling wrote:
> Greetings Shai --
>
> On Saturday, December 26, 2015 at 3:57:00 PM UTC-5, Shai Berger wrote:
> > Hi Doug,
> >
> > On Saturday 26 December 2015 21:08:58 Doug Epling wrote:
> > > Thanks Carl --
> > >
> > > Here is a good example:
> > >
> > > I wanted to read-up on the Form class. First thing I did was go here:
> > >
> > > https://docs.djangoproject.com/en/1.9/search/?q=Form
> > >
> > > yadda, yadda, yadda, recipe, recipe, .... where is the simple list of
> > > attributes contained in this class?
> >
> > So, this already seems odd. You want to read up on it, but you're not
> > actually
> > interested in what people wrote up on it?
>
> I am sorry if someone's carefully crafted 'how-to`s' got stepped-on by my
> criticism, really, criticism stings. But this does not make the criticism
> invalid. In fact, good writers should relish the sting of criticism
> because it makes them better.
>
An old Hebrew proverb says (paraphrased), before you call upon others to take
out the pick between their teeth, take out the wooden beam between your eyes.
I call you out on what seems like a contradiction in your writing, and instead
of explaining it, you turn to general talk of criticism -- as if any criticism
of your text is motivated by being personally hurt by it.
Again: Please explain why, when you want to "read up" on a topic, a general
explanation of that topic is not suitable.
> > It sounds like you're looking for a Javadoc-style reference. I always had
> > the
> > feelng that Django avoided these by design; a "simple list of attributes"
> > is
> > usually not helpful for a human who wants to get something done.
> >
> > > [...] But
>
> Just in general, it is unproductive to take things out-of-context, and
> respond only to things you pick and choose.
>
As opposed to responding only to things you pick-and-choose, taken out of
context, while still quoting the parts you ignore -- which is what you're
doing, when you pretend I didn't say that simple lists of attributes, as you
asked for, are not there by design?
> > > what-the-heck is this 'six' we import from django.util? So I go here:
> > https://docs.djangoproject.com/en/1.9/search/?q=django.utils&release=1.9&
> > pa
> >
> > > ge=1
> > >
> > > Here I reach a dead end. I could go farther, but this is all a
> > > side-track. This isn't even relevant to what I am working on. And it
> >
> > is
> >
> > > entirely possible 'six' is something I should just know about and
> > > don't.
> >
> > It is something you should either know about, or not care about. As far
> > as
>
> Au contraire, mon frere!
>
> > forms are concerned, it is just an implementation detail. So if you're
> > looking
> > to use forms, you should probably not care about it. If you're looking to
> > hack
>
> Please try to stay on topic. The topic is documentation. The excursion
> into the Form class, specifically, was only exemplary.
>
Wait, so it is good for you to bring up an example, but bad if someone else
looks at it and shows that, at least in part, it does not exemplify what you
claimed it did?
> > on forms, the issue of Python 2/3 compatibility (which six is a solution
> > for)
> > should be familiar to you; and if it isn't, and you're already reading
> > source
> > files, you just might open the six.py module, where you'll find a
> > docstring
> > which reads:
> >
> > """Utilities for writing code that runs on Python 2 and 3"""
> >
> > > So is anyone convinced yet?
> >
> > So, I'm not convinced. In particular, I don't understand the frame of
> > mind
>
> My frame of mind is that we should put the entire text of this section:
>
No. This is not some goal you are trying to reach. Perhaps it is the way to
reach some such goal. But it is still completely unclear what that goal is. A
goal would be "making it easier to find information about a specific method", or
"making it easier to understand how to achieve some task", or "making some
text easier to read for a novice".
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.
I'm leaving quotes in full here, as you requested, and to help demonstrate
that it isn't useful at all. It is just "visual noise" that most readers will
skip over.
On Sunday 27 December 2015 05:42:53 Doug Epling wrote:
> Greetings Shai --
>
> On Saturday, December 26, 2015 at 3:57:00 PM UTC-5, Shai Berger wrote:
> > Hi Doug,
> >
> > On Saturday 26 December 2015 21:08:58 Doug Epling wrote:
> > > Thanks Carl --
> > >
> > > Here is a good example:
> > >
> > > I wanted to read-up on the Form class. First thing I did was go here:
> > >
> > > https://docs.djangoproject.com/en/1.9/search/?q=Form
> > >
> > > yadda, yadda, yadda, recipe, recipe, .... where is the simple list of
> > > attributes contained in this class?
> >
> > So, this already seems odd. You want to read up on it, but you're not
> > actually
> > interested in what people wrote up on it?
>
> I am sorry if someone's carefully crafted 'how-to`s' got stepped-on by my
> criticism, really, criticism stings. But this does not make the criticism
> invalid. In fact, good writers should relish the sting of criticism
> because it makes them better.
>
out the pick between their teeth, take out the wooden beam between your eyes.
I call you out on what seems like a contradiction in your writing, and instead
of explaining it, you turn to general talk of criticism -- as if any criticism
of your text is motivated by being personally hurt by it.
Again: Please explain why, when you want to "read up" on a topic, a general
explanation of that topic is not suitable.
> > It sounds like you're looking for a Javadoc-style reference. I always had
> > the
> > feelng that Django avoided these by design; a "simple list of attributes"
> > is
> > usually not helpful for a human who wants to get something done.
> >
> > > [...] But
>
> Just in general, it is unproductive to take things out-of-context, and
> respond only to things you pick and choose.
>
context, while still quoting the parts you ignore -- which is what you're
doing, when you pretend I didn't say that simple lists of attributes, as you
asked for, are not there by design?
> > > what-the-heck is this 'six' we import from django.util? So I go here:
> > https://docs.djangoproject.com/en/1.9/search/?q=django.utils&release=1.9&
> > pa
> >
> > > ge=1
> > >
> > > Here I reach a dead end. I could go farther, but this is all a
> > > side-track. This isn't even relevant to what I am working on. And it
> >
> > is
> >
> > > entirely possible 'six' is something I should just know about and
> > > don't.
> >
> > It is something you should either know about, or not care about. As far
> > as
>
> Au contraire, mon frere!
>
> > forms are concerned, it is just an implementation detail. So if you're
> > looking
> > to use forms, you should probably not care about it. If you're looking to
> > hack
>
> Please try to stay on topic. The topic is documentation. The excursion
> into the Form class, specifically, was only exemplary.
>
looks at it and shows that, at least in part, it does not exemplify what you
claimed it did?
> > on forms, the issue of Python 2/3 compatibility (which six is a solution
> > for)
> > should be familiar to you; and if it isn't, and you're already reading
> > source
> > files, you just might open the six.py module, where you'll find a
> > docstring
> > which reads:
> >
> > """Utilities for writing code that runs on Python 2 and 3"""
> >
> > > So is anyone convinced yet?
> >
> > So, I'm not convinced. In particular, I don't understand the frame of
> > mind
>
> My frame of mind is that we should put the entire text of this section:
>
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".
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.
Samuel Bishop
Dec 27, 2015, 3:44:06 AM12/27/15
to Django developers (Contributions to Django itself)
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
Sam
Wim Feijen
Dec 27, 2015, 10:19:05 AM12/27/15
to Django developers (Contributions to Django itself)
Hi Doug,
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 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
Tim Graham
Dec 27, 2015, 10:41:57 AM12/27/15
to Django developers (Contributions to Django itself)
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.
Doug Epling
Dec 27, 2015, 2:47:35 PM12/27/15
to Django developers (Contributions to Django itself)
Again, I am sorry if my comments have ruffled anyone's feathers. I am not going to argue. My sole intent is a positive one. And, indeed, I am humbled by the ongoing work of this community over a period of time that I, until now, have not been involved.
I beleive, it is my impression, that between Django 1.1 and now, on the verge of its second major version, there has been a tremendous amount of Python software develpment. And the internal commenting as well as the public documentation has trailed along ad hoc.
It can be said without legitimate reproach that any system whether it is thermodynamics or a system of communication, such as our documentation, will naturally tend toward entropy unless something actively intervenes. And we have developed a fairly complex system compared to, say, werksgeud.
That patchwork approach has disrupted a flow of utility for users in both public documentation and internal commenting. If this is true, Django has strayed from principles of its foundation. And our motto: "The framework for perfectionists with deadlines."; holds true only until fininding oneself lost in the documentation.
Tim is exactly right; this is with no doubt a non-trivial issue. Is Django capable of tackling non-trivial issues? If not I am in the wrong place (a challenge to Django, relax, it's not personal) because I believe Django should be setting the standard. And this issue will not be resolved by an ad hoc approach; meaning our traditional methodology of a problem ticket reporting process is not amenable. This calls for something else if it calls for anything.
However, Wim has a good idea! Some exploratory research is a very reasonable first step toward an objective problem definition. Tim, how hard would it be to present every visitor to the documentation with a pop-up (or some other kind of) general invitation to visit a link on Survey Monkey to help us with some feedback?
On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote:
Tim Graham
Dec 27, 2015, 5:42:49 PM12/27/15
to Django developers (Contributions to Django itself)
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/
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/
Doug Epling
Dec 27, 2015, 9:06:46 PM12/27/15
to Django developers (Contributions to Django itself)
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.
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.
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.
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.
On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote:
Tim Allen
Dec 28, 2015, 5:44:49 AM12/28/15
to Django developers (Contributions to Django itself)
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
Aymeric Augustin
Dec 28, 2015, 8:48:28 AM12/28/15
to django-d...@googlegroups.com
On 27 déc. 2015, at 23:42, Tim Graham <timog...@gmail.com> wrote:
> 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.
> 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.
> 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?
--
Aymeric.
Samuel Bishop
Dec 28, 2015, 12:40:13 PM12/28/15
to Django developers (Contributions to Django itself)
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.
Tim Graham
Dec 28, 2015, 1:17:03 PM12/28/15
to Django developers (Contributions to Django itself)
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
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
Daniele Procida
Dec 28, 2015, 7:52:36 PM12/28/15
to Django Developers
On Mon, Dec 28, 2015, Samuel Bishop <lucra...@gmail.com> wrote:
>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:
>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.
* 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
Eric Holscher
Dec 28, 2015, 11:31:30 PM12/28/15
to Django developers (Contributions to Django itself)
On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:
On Mon, Dec 28, 2015, Samuel Bishop <lucra...@gmail.com> wrote:
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 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
Tim Graham
Dec 29, 2015, 11:25:40 AM12/29/15
to Django developers (Contributions to Django itself)
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.
Let me know if it helps and what could be better.
Tim Allen
Dec 29, 2015, 4:48:37 PM12/29/15
to Django developers (Contributions to Django itself)
Tim: that's definitely a big help, but still a click away. I'm just brainstorming here, please bear with me!
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?
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
Tim Graham
Dec 29, 2015, 5:17:31 PM12/29/15
to Django developers (Contributions to Django itself)
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
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
Eric Holscher
Dec 30, 2015, 12:34:28 AM12/30/15
to Django developers (Contributions to Django itself)
On Tuesday, December 29, 2015 at 2:17:31 PM UTC-8, Tim Graham wrote:
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
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)
Doug Epling
Jan 1, 2016, 5:35:58 PM1/1/16
to Django developers (Contributions to Django itself)
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.
Tim Graham
Jan 1, 2016, 6:19:06 PM1/1/16
to Django developers (Contributions to Django itself)
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.
I'm happy to support you if you have some specific next steps in mind.
Doug Epling
Jan 1, 2016, 11:48:24 PM1/1/16
to Django developers (Contributions to Django itself)
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.
Aymeric Augustin
Jan 2, 2016, 4:51:15 AM1/2/16
to django-d...@googlegroups.com
On 2 janv. 2016, at 05:48, Doug Epling <wmdoug...@gmail.com> wrote:
> 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,
> 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.
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.
Ned Batchelder
Jan 2, 2016, 7:26:26 AM1/2/16
to django-d...@googlegroups.com
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.
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.
--
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-develop...@googlegroups.com.
To post to this group, send email to django-d...@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.
Message has been deleted
Doug Epling
Jan 3, 2016, 8:59:23 PM1/3/16
to Django developers (Contributions to Django itself)
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,
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,
Doug Epling
Jan 3, 2016, 10:59:29 PM1/3/16
to Django developers (Contributions to Django itself)
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,
Scot Hacker
Jan 4, 2016, 2:45:56 AM1/4/16
to Django developers (Contributions to Django itself)
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
Doug Epling
Jan 4, 2016, 7:14:56 PM1/4/16
to Django developers (Contributions to Django itself)
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,
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,
Tim Allen
Jan 5, 2016, 10:10:01 AM1/5/16
to Django developers (Contributions to Django itself)
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
On Monday, January 4, 2016 at 2:45:56 AM UTC-5, Scot Hacker wrote:
Doug Epling
Jul 14, 2016, 11:23:27 AM7/14/16
to Django developers (Contributions to Django itself)
On Friday, January 1, 2016 at 11:48:24 PM UTC-5, Doug Epling wrote:
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.
Reply all
Reply to author
Forward
0 new messages