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/9fa508d3-6dcc-4fd1-88c7-51845e0a00cb%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
