Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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,

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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

Re: structural & functional review of django documentation

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,

Re: structural & functional review of django documentation

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

structural & functional review of django documentation

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