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 <lucra...@gmail.com> wrote: >>>> The main existing sections are: >>>> >>>> * tutorials (/intro) >>>> >>>> Tutorials take the new user by the hand through a series of steps. The >>>> important thing isn't to explain all the steps, but to achieve something >>>> useful with a minimum of effort. >>>> >>>> After every step of a tutorial, the user should have something that >>>> works, even if they barely understand what is happening (and it's not >>>> necessary for them to understand, that can come later. What matters is >>>> that >>>> they are successful). >>>> >>>> * how-to guides (/howto) >>>> >>>> How-to guides are recipes that take the user through steps in key >>>> subjects. They are more advanced than tutorials and assume a lot more >>>> about >>>> what the user already knows than tutorials do, and unlike documents in the >>>> tutorial they can stand alone. >>>> >>>> * discussion and explanation (/topic) >>>> >>>> Aimed at explaining (at a fairly high level) rather than doing. >>>> >>>> * reference (/ref) >>>> >>>> Technical reference for APIs, key models and so on. It doesn't need to >>>> explain so much as describe and instruct. >>>> >>>> >>> I think the above post does a good job of describing the layout, and >>> something similar should be included in the docs. Without having read >>> Jacob's posts on the subject, there is nothing in the official docs that >>> gives the reader an understanding that this is how things are laid out, as >>> far as I know. >>> >>> I think the underlying structure makes sense, and it seems that mostly >>> people are just upset about the lack of a pure auto-generated code >>> reference. I believe historically that this has been excluded explicitly, >>> not because of lack of technology. There is no use of autodoc in the Django >>> tree, even where it might make sense. >>> >>> At Django Under the Hood this year, I had a few conversations with folks >>> about rethinking and explicitly defining these policies. I think it makes a >>> lot of sense to write down the logic and structure behind these decisions >>> in a DEP, and explain the layout to doc users in a few places in the >>> documentation explicitly. >>> >>> Cheers, >>> Eric >>> >> -- 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/939e7dec-39cf-4605-919c-48dbe8692d2a%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
