On Mon, Dec 28, 2015, Samuel Bishop <lucract...@gmail.com> 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.
