Re: structural & functional review of django documentation

[Doug Epling]

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.
 

> 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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/facc1359-7ec6-4683-b5f4-eeeabbc29e20%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Allen]

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:
>
> 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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/b0f50682-2c4b-42f8-a4b9-33fc3121f315%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Doug Epling]

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,

On Monday, January 4, 2016 at 2:45:56 AM UTC-5, Scot Hacker wrote:
>
> 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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/f772dd19-967b-48a5-9926-9bf723b698a3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Scot Hacker]

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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/da7ae84d-7696-4705-b8a3-115c9ec40b94%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Doug Epling]

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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/da51873a-7606-4c69-8788-c3e97471ce17%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Doug Epling]

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,

On Saturday, January 2, 2016 at 4:51:15 AM UTC-5, Aymeric Augustin wrote:
>
> On 2 janv. 2016, at 05:48, Doug Epling  
> 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, 
>
> 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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/00f54342-b056-4b8d-8165-c921777cc11d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
404
ability
able
abstract
accept
accepted
accepts
access
according
account
action
actions
actually
add
added
adding
addition
additional
address
adds
admin
aggregate
algorithm
alias
allow
allowed
allows
already
also
always
another
anything
apache
api
app
appear
application
applications
applied
apply
appropriate
apps
arent
args
argument
arguments
around
article
associated
attribute
attributes
authentication
author
authors
automatically
availability
available
avoid
aware
back
backend
backends
bar
base
based
basic
becomes
behavior
best

Re: structural & functional review of django documentation

[Doug Epling]

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,

On Saturday, January 2, 2016 at 4:51:15 AM UTC-5, Aymeric Augustin wrote:
>
> On 2 janv. 2016, at 05:48, Doug Epling  
> 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, 
>
> 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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/676fbf93-acee-4c23-8444-a4c2d93b0ca3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
base.txt, signing.txt, database-functions.txt, generic-editing.txt, 
admindocs.txt, sql.txt, modwsgi.txt, email.txt, admin.txt, api.txt, 
flatpages.txt, index.txt, distributions.txt, middleware.txt, 
mixins-single-object.txt, commands.txt, forms-api.txt, 
conditional-expressions.txt, coding-style.txt, organization.txt, relations.txt, 
deployment.txt, custom-management-commands.txt, design-philosophies.txt, 
howto-release-django.txt, widgets.txt, mixins2.txt, actions.txt, 
api-stability.txt, utils2.txt, custom-file-storage.txt, tutorial01.txt, 
install2.txt, submitting-patches.txt, 

Re: structural & functional review of django documentation

[Ned Batchelder]

Doug, I'm having a hard time understanding you. You are pointing at data 
and coming to completely different conclusions than I do. Below you say, 
"The Django cadre must regularly ask about the state of public sentiment 
and satisfaction, because it is reckless to do otherwise."  This is 
after you examined the 3000 (!) responses to a survey of the Django 
community. Is there some other way the Django team should ask about 
public sentiment?


You also say, "If the consensus is to deny a need, the documentation 
will continue to be an afterthought," after you yourself noticed that 
the word "documentation" was a prominent answer to, "What's your 
favorite thing about Django?"  Seems like the public has been surveyed, 
and they like the docs.


You've started a discussion here, and in response, people have come up 
with concrete improvements to the docs, and are discussing other ideas.  
But you still seem to be approaching this as if 1) the docs are widely 
regarded as bad, and 2) nothing will be done about it.


Am I missing something?

--Ned.


On 1/1/16 5:35 PM, Doug Epling wrote:


I know some might have hoped I would just go away. But generally 
speaking when I say I will do something I follow through. At the very 
least I can work on the Glossary.



I looked at the poll of developers from last May. I loaded the results 
in an R data.frame, but I did not find any relationships within that 
data at all. I wonder what conclusions the core team was able to draw 
from that other than, like, 77 percent of the responses came within 48 
hours of its release. This fact must mean something,



Below is a wordcloud representation of the frequency of most used 
words under the "What's your favorite thing about Django?" item.



This doesn't really mean a lot, but it is kind of neat to look at.


You can notice the prominance of 'documentation', and 'orm'.


Again, these probably don't mean a whole lot, although developer folks 
sure exhibited an eagerness to express themselves. And you only need 
to skim over those results to see that a lot of Django regulars, the 
developers, really like the documentation. It would be interesting to 
hear why or how these folks use documentation that causes them such 
affinity for the docs.



Without those why-or-how answers to user interface questions, users 
defined as extremely active members of the developer community, it is 
hard to balance with the criticism that pops up here-and-there, 
including my own.



This discussion begs to transpire among members of the core team 
because nothing can change unless they see fit. If the consensus is to 
deny a need, the documentation will continue to be an afterthought.



The Django core developers are not the only public involved. Some 
might say they are in service to the public at large. The Django cadre 
must regularly ask about the state of public sentiment and 
satisfaction, because it is reckless to do otherwise.


Rplot_pos.png


On Sunday, December 27, 2015 at 5:42:49 PM UTC-5, Tim Graham wrote:

Adding a survey link is not difficult. We conducted a community
survey [1] earlier this year with one question related to
documentation, "What parts of the Django documentation do you find
most useful?" What questions to ask and how to turn the answers
into actionable items is the part I'm not sure about and maybe you
could advise on.

In my view, Django's docs haven't strayed from the "topics",
"reference", and "how-to" division that we've had since 1.0 or so.
Are you aware of this grouping? Maybe a "how the docs are
organized" section on the index page would help communicate that
and make it more intuitive where to look for something?

I'll admit I'm skeptical of a wholesale reorganization to this
structure for several reasons:
1. It'll be confusing for existing users who are familiar with the
current section.
2. It'll make it more difficult or impossible to backport
documentation enhancements to the stable version of the docs
(assuming we don't also reorganize them with same structure)
3. It'll create an opportunity for broken links (obviously we
could mitigate this to some extent by adding redirects to the new
locations).

It seems to me you were pretty close to finding what you were
looking for at https://docs.djangoproject.com/en/1.9/ref/forms/
 (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/


On Sunday, December 27, 2015 at 2:47:35 PM UTC-5, Doug Epling wrote:

Again, I am sorry if my comments have ruffled anyone's
feathers.  I am not going to argue.  My sole intent is a
positive one.  And, indeed, I am humbled by the 

Re: structural & functional review of django documentation

[Aymeric Augustin]

On 2 janv. 2016, at 05:48, Doug Epling  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,

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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/2C085DD1-0F56-4ABF-91C7-A3E4D96E345D%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[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.

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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/d9f4aa9a-1d9c-4b8b-8e2b-b6c9427b4ce1%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Graham]

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.

On Friday, January 1, 2016 at 5:35:58 PM UTC-5, Doug Epling wrote:
>
> 
>
> I know some might have hoped I would just go away. But generally speaking 
> when I say I will do something I follow through. At the very least I can 
> work on the Glossary.
>
> I looked at the poll of developers from last May. I loaded the results in 
> an R data.frame, but I did not find any relationships within that data at 
> all. I wonder what conclusions the core team was able to draw from that 
> other than, like, 77 percent of the responses came within 48 hours of its 
> release. This fact must mean something,
>
> Below is a wordcloud representation of the frequency of most used words 
> under the "What's your favorite thing about Django?" item.
>
> This doesn't really mean a lot, but it is kind of neat to look at.
>
> You can notice the prominance of 'documentation', and 'orm'.
>
> Again, these probably don't mean a whole lot, although developer folks 
> sure exhibited an eagerness to express themselves. And you only need to 
> skim over those results to see that a lot of Django regulars, the 
> developers, really like the documentation. It would be interesting to hear 
> why or how these folks use documentation that causes them such affinity for 
> the docs.
>
> Without those why-or-how answers to user interface questions, users 
> defined as extremely active members of the developer community, it is hard 
> to balance with the criticism that pops up here-and-there, including my own.
>
> This discussion begs to transpire among members of the core team because 
> nothing can change unless they see fit. If the consensus is to deny a need, 
> the documentation will continue to be an afterthought.
>
> The Django core developers are not the only public involved. Some might 
> say they are in service to the public at large. The Django cadre must 
> regularly ask about the state of public sentiment and satisfaction, because 
> it is reckless to do otherwise.
>
> [image: Rplot_pos.png]
>
> On Sunday, December 27, 2015 at 5:42:49 PM UTC-5, Tim Graham wrote:
>>
>> Adding a survey link is not difficult. We conducted a community survey 
>> [1] earlier this year with one question related to documentation, "What 
>> parts of the Django documentation do you find most useful?" What questions 
>> to ask and how to turn the answers into actionable items is the part I'm 
>> not sure about and maybe you could advise on.
>>
>> In my view, Django's docs haven't strayed from the "topics", "reference", 
>> and "how-to" division that we've had since 1.0 or so. Are you aware of this 
>> grouping? Maybe a "how the docs are organized" section on the index page 
>> would help communicate that and make it more intuitive where to look for 
>> something?
>>
>> I'll admit I'm skeptical of a wholesale reorganization to this structure 
>> for several reasons:
>> 1. It'll be confusing for existing users who are familiar with the 
>> current section.
>> 2. It'll make it more difficult or impossible to backport documentation 
>> enhancements to the stable version of the docs (assuming we don't also 
>> reorganize them with same structure)
>> 3. It'll create an opportunity for broken links (obviously we could 
>> mitigate this to some extent by adding redirects to the new locations).
>>
>> It seems to me you were pretty close to finding what you were looking for 
>> at https://docs.djangoproject.com/en/1.9/ref/forms/ (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/
>>
>> On Sunday, December 27, 2015 at 2:47:35 PM UTC-5, Doug Epling wrote:
>>>
>>> Again, I am sorry if my comments have ruffled anyone's feathers.  I am 
>>> not going to argue.  My sole intent is a positive one.  And, indeed, I am 
>>> humbled by the ongoing work of this community over a period of time that I, 
>>> until now, have not been involved.
>>>
>>> I beleive, it is my impression, that between Django 1.1 and now, on the 
>>> verge of its second major version, there has been a tremendous amount of 
>>> Python software develpment.  And the internal commenting as well as the 
>>> public documentation has trailed along ad hoc.
>>>
>>> It can be said without legitimate reproach that any system whether it is 
>>> thermodynamics or a system of communication, such as our documentation, 
>>> will naturally tend toward entropy unless something 

Re: structural & functional review of django documentation

[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]

On Sunday, December 27, 2015 at 5:42:49 PM UTC-5, Tim Graham wrote:
>
> Adding a survey link is not difficult. We conducted a community survey [1] 
> earlier this year with one question related to documentation, "What parts 
> of the Django documentation do you find most useful?" What questions to ask 
> and how to turn the answers into actionable items is the part I'm not sure 
> about and maybe you could advise on.
>
> In my view, Django's docs haven't strayed from the "topics", "reference", 
> and "how-to" division that we've had since 1.0 or so. Are you aware of this 
> grouping? Maybe a "how the docs are organized" section on the index page 
> would help communicate that and make it more intuitive where to look for 
> something?
>
> I'll admit I'm skeptical of a wholesale reorganization to this structure 
> for several reasons:
> 1. It'll be confusing for existing users who are familiar with the current 
> section.
> 2. It'll make it more difficult or impossible to backport documentation 
> enhancements to the stable version of the docs (assuming we don't also 
> reorganize them with same structure)
> 3. It'll create an opportunity for broken links (obviously we could 
> mitigate this to some extent by adding redirects to the new locations).
>
> It seems to me you were pretty close to finding what you were looking for 
> at https://docs.djangoproject.com/en/1.9/ref/forms/ (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/
>
> On Sunday, December 27, 2015 at 2:47:35 PM UTC-5, Doug Epling wrote:
>>
>> Again, I am sorry if my comments have ruffled anyone's feathers.  I am 
>> not going to argue.  My sole intent is a positive one.  And, indeed, I am 
>> humbled by the ongoing work of this community over a period of time that I, 
>> until now, have not been involved.
>>
>> I beleive, it is my impression, that between Django 1.1 and now, on the 
>> verge of its second major version, there has been a tremendous amount of 
>> Python software develpment.  And the internal commenting as well as the 
>> public documentation has trailed along ad hoc.
>>
>> It can be said without legitimate reproach that any system whether it is 
>> thermodynamics or a system of communication, such as our documentation, 
>> will naturally tend toward entropy unless something actively intervenes. 
>>  And we have developed a fairly complex system compared to, say, werksgeud. 
>>
>> That patchwork approach has disrupted a flow of utility for users in both 
>> public documentation and internal commenting.  If this is true, Django has 
>> strayed from principles of its foundation.  And our motto: "The framework 
>> for perfectionists with deadlines."; holds true only until fininding 
>> oneself lost in the documentation.
>>
>> Tim is exactly right; this is with no doubt a non-trivial issue.  Is 
>> Django capable of tackling non-trivial issues?  If not I am in the wrong 
>> place (a challenge to Django, relax, it's not personal) because I believe 
>> 

Re: structural & functional review of django documentation

[Eric Holscher]

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)
 

>
>
> On Tuesday, December 29, 2015 at 4:48:37 PM UTC-5, Tim Allen wrote:
>>
>> 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
>>
>> On Tuesday, December 29, 2015 at 11:25:40 AM UTC-5, Tim Graham wrote:
>>>
>>> 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.
>>>
>>> On Monday, December 28, 2015 at 11:31:30 PM UTC-5, Eric Holscher wrote:



 On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:
>
> On Mon, Dec 28, 2015, Samuel Bishop  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 

Re: structural & functional review of django documentation

[Tim Graham]

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

On Tuesday, December 29, 2015 at 4:48:37 PM UTC-5, Tim Allen wrote:
>
> 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
>
> On Tuesday, December 29, 2015 at 11:25:40 AM UTC-5, Tim Graham wrote:
>>
>> 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.
>>
>> On Monday, December 28, 2015 at 11:31:30 PM UTC-5, Eric Holscher wrote:
>>>
>>>
>>>
>>> On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:

 On Mon, Dec 28, 2015, Samuel Bishop  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 
>>>
>>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this 

Re: structural & functional review of django documentation

[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

On Tuesday, December 29, 2015 at 11:25:40 AM UTC-5, Tim Graham wrote:
>
> 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.
>
> On Monday, December 28, 2015 at 11:31:30 PM UTC-5, Eric Holscher wrote:
>>
>>
>>
>> On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:
>>>
>>> On Mon, Dec 28, 2015, Samuel Bishop  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 
>>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/12221065-6358-4a20-a383-60f3aac5f240%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Graham]

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.

On Monday, December 28, 2015 at 11:31:30 PM UTC-5, Eric Holscher wrote:
>
>
>
> On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:
>>
>> On Mon, Dec 28, 2015, Samuel Bishop  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 
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/9fa508d3-6dcc-4fd1-88c7-51845e0a00cb%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Eric Holscher]

On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote:
>
> On Mon, Dec 28, 2015, Samuel Bishop  
> 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 

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/0daa98a8-6714-4f76-adb2-ea5ced43d361%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Daniele Procida]

On Mon, Dec 28, 2015, Samuel Bishop  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:

* 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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/20151229005216.254922486%40mail.wservices.ch.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Graham]

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

On Monday, December 28, 2015 at 12:40:13 PM UTC-5, Samuel Bishop wrote:
>
> 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. 
>
> On Monday, 28 December 2015 06:42:49 UTC+8, Tim Graham wrote:
>>
>> Adding a survey link is not difficult. We conducted a community survey 
>> [1] earlier this year with one question related to documentation, "What 
>> parts of the Django documentation do you find most useful?" What questions 
>> to ask and how to turn the answers into actionable items is the part I'm 
>> not sure about and maybe you could advise on.
>>
>> In my view, Django's docs haven't strayed from the "topics", "reference", 
>> and "how-to" division that we've had since 1.0 or so. Are you aware of this 
>> grouping? Maybe a "how the docs are organized" section on the index page 
>> would help communicate that and make it more intuitive where to look for 
>> something?
>>
>> I'll admit I'm skeptical of a wholesale reorganization to this structure 
>> for several reasons:
>> 1. It'll be confusing for existing users who are familiar with the 
>> current section.
>> 2. It'll make it more difficult or impossible to backport documentation 
>> enhancements to the stable version of the docs (assuming we don't also 
>> reorganize them with same structure)
>> 3. It'll create an opportunity for broken links (obviously we could 
>> mitigate this to some extent by adding redirects to the new locations).
>>
>> It seems to me you were pretty close to finding what you were looking for 
>> at https://docs.djangoproject.com/en/1.9/ref/forms/ (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/
>>
>> On Sunday, December 27, 2015 at 2:47:35 PM UTC-5, Doug Epling wrote:
>>>
>>> Again, I am sorry if my comments have ruffled anyone's feathers.  I am 
>>> not going to argue.  My sole intent is a positive one.  And, indeed, I am 
>>> humbled by the ongoing work of this community over a period of time that I, 
>>> until now, have not been involved.
>>>
>>> I beleive, it is my impression, that between Django 1.1 and now, on the 
>>> verge of its second major version, there has been a tremendous amount of 
>>> Python software develpment.  And the internal commenting as well as the 
>>> public documentation has trailed along ad hoc.
>>>
>>> It can be said without legitimate reproach that any system whether it is 
>>> thermodynamics or a system of communication, such as our documentation, 
>>> will naturally tend toward entropy unless something actively intervenes. 
>>>  And we have developed a fairly 

Re: structural & functional review of django documentation

[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. 

On Monday, 28 December 2015 06:42:49 UTC+8, Tim Graham wrote:
>
> Adding a survey link is not difficult. We conducted a community survey [1] 
> earlier this year with one question related to documentation, "What parts 
> of the Django documentation do you find most useful?" What questions to ask 
> and how to turn the answers into actionable items is the part I'm not sure 
> about and maybe you could advise on.
>
> In my view, Django's docs haven't strayed from the "topics", "reference", 
> and "how-to" division that we've had since 1.0 or so. Are you aware of this 
> grouping? Maybe a "how the docs are organized" section on the index page 
> would help communicate that and make it more intuitive where to look for 
> something?
>
> I'll admit I'm skeptical of a wholesale reorganization to this structure 
> for several reasons:
> 1. It'll be confusing for existing users who are familiar with the current 
> section.
> 2. It'll make it more difficult or impossible to backport documentation 
> enhancements to the stable version of the docs (assuming we don't also 
> reorganize them with same structure)
> 3. It'll create an opportunity for broken links (obviously we could 
> mitigate this to some extent by adding redirects to the new locations).
>
> It seems to me you were pretty close to finding what you were looking for 
> at https://docs.djangoproject.com/en/1.9/ref/forms/ (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/
>
> On Sunday, December 27, 2015 at 2:47:35 PM UTC-5, Doug Epling wrote:
>>
>> Again, I am sorry if my comments have ruffled anyone's feathers.  I am 
>> not going to argue.  My sole intent is a positive one.  And, indeed, I am 
>> humbled by the ongoing work of this community over a period of time that I, 
>> until now, have not been involved.
>>
>> I beleive, it is my impression, that between Django 1.1 and now, on the 
>> verge of its second major version, there has been a tremendous amount of 
>> Python software develpment.  And the internal commenting as well as the 
>> public documentation has trailed along ad hoc.
>>
>> It can be said without legitimate reproach that any system whether it is 
>> thermodynamics or a system of communication, such as our documentation, 
>> will naturally tend toward entropy unless something actively intervenes. 
>>  And we have developed a fairly complex system compared to, say, werksgeud. 
>>
>> That patchwork approach has disrupted a flow of utility for users in both 
>> public documentation and internal commenting.  If this is true, Django has 
>> strayed from principles of its foundation.  And our motto: "The framework 
>> for perfectionists with deadlines."; holds true only until fininding 
>> oneself lost in the documentation.
>>
>> Tim is exactly right; this is with no doubt a non-trivial issue.  Is 
>> Django capable of tackling non-trivial issues?  If not I am in the wrong 
>> place (a challenge to Django, relax, it's not personal) because I believe 
>> Django should be setting the standard.  And this issue will not be resolved 
>> by an ad hoc approach; meaning our traditional methodology of a problem 
>> ticket reporting process is not amenable.  This calls for something else if 
>> it calls for anything.
>>
>> However, Wim has a good idea!  Some exploratory research is a very 
>> reasonable first step toward an 

Re: structural & functional review of django documentation

[Aymeric Augustin]

On 27 déc. 2015, at 23:42, Tim Graham  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.

> 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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/DD6E5C59-85B4-482C-AC8D-03FCB3ECCB17%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Allen]

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

On Sunday, December 27, 2015 at 9:06:46 PM UTC-5, Doug Epling wrote:
>
> 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.
>
> On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote:
>>
>> I filed bug report 
>> #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?
>>
>>
>>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/025ed576-59e1-45cf-9cbe-be11ee56115d%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[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 .  


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:
>
> I filed bug report 
> #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?
>
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/627694e7-502e-4b1e-9c6b-b7bd78da8653%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[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 
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/

On Sunday, December 27, 2015 at 2:47:35 PM UTC-5, Doug Epling wrote:
>
> Again, I am sorry if my comments have ruffled anyone's feathers.  I am not 
> going to argue.  My sole intent is a positive one.  And, indeed, I am 
> humbled by the ongoing work of this community over a period of time that I, 
> until now, have not been involved.
>
> I beleive, it is my impression, that between Django 1.1 and now, on the 
> verge of its second major version, there has been a tremendous amount of 
> Python software develpment.  And the internal commenting as well as the 
> public documentation has trailed along ad hoc.
>
> It can be said without legitimate reproach that any system whether it is 
> thermodynamics or a system of communication, such as our documentation, 
> will naturally tend toward entropy unless something actively intervenes. 
>  And we have developed a fairly complex system compared to, say, werksgeud. 
>
> That patchwork approach has disrupted a flow of utility for users in both 
> public documentation and internal commenting.  If this is true, Django has 
> strayed from principles of its foundation.  And our motto: "The framework 
> for perfectionists with deadlines."; holds true only until fininding 
> oneself lost in the documentation.
>
> Tim is exactly right; this is with no doubt a non-trivial issue.  Is 
> Django capable of tackling non-trivial issues?  If not I am in the wrong 
> place (a challenge to Django, relax, it's not personal) because I believe 
> Django should be setting the standard.  And this issue will not be resolved 
> by an ad hoc approach; meaning our traditional methodology of a problem 
> ticket reporting process is not amenable.  This calls for something else if 
> it calls for anything.
>
> However, Wim has a good idea!  Some exploratory research is a very 
> reasonable first step toward an objective problem definition.  Tim, how 
> hard would it be to present every visitor to the documentation with a 
> pop-up (or some other kind of) general invitation to visit a link on Survey 
> Monkey to help us with some feedback?
>
> On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote:
>>
>> I filed bug report 
>> #25952 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?
>>
>>
>>

-- 
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 

Re: structural & functional review of django documentation

[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?

On Friday, December 18, 2015 at 7:02:56 PM UTC-5, Doug Epling wrote:
>
> I filed bug report 
> #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?
>
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/373526bb-be5e-4ca0-b5cb-2ae558c996b8%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Tim Graham]

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.

On Sunday, December 27, 2015 at 10:19:05 AM UTC-5, Wim Feijen wrote:
>
> 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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/5e3ad3cf-d822-455f-862e-12cedfe8bb5f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Wim Feijen]

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+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/39421256-8911-4fc7-800d-93d29a091d92%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Doug Epling]

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=1.9 
> > 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. 
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/566faeb6-a679-4e9a-8278-c0eeeff77e0e%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: structural & functional review of django documentation

[Shai Berger]

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
> 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=1.9
> 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"""

> 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.

Re: structural & functional review of django documentation

[Carl Meyer]

Hi Doug,

On 12/18/2015 04:35 PM, Doug Epling wrote:
> I filed bug report
> 
> #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).

>  And I referenced this post
> ,
> 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. 

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

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/5674A416.8080103%40oddbird.net.
For more options, visit https://groups.google.com/d/optout.


signature.asc
Description: OpenPGP digital signature

structural & functional review of django documentation

[Doug Epling]

I filed bug report 
#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?


-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/460b1aa4-bbb6-45e2-8619-0fb6d9af4f62%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.