On Monday, December 28, 2015 at 4:52:36 PM UTC-8, Daniele Procida wrote: > > On Mon, Dec 28, 2015, Samuel Bishop <[email protected] <javascript:>> > 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 [email protected]. To post to this group, send email to [email protected]. 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.
