On Sun, Jul 4, 2010 at 2:05 PM, dffdgsdfgsdfhjhtre <nbvf...@gmail.com> wrote: > There are two types of documentation, "reference" documentation > (articles explaining all about one specific object such as slugify or > the Feed class), and "topical" documentation (articles explaining how > to do stuff like write templates).
On Sun, Jul 4, 2010 at 9:06 PM, dffdgsdfgsdfhjhtre <nbvf...@gmail.com> wrote: > On Jul 4, 7:38 pm, Flávio Amieiro <flavioamie...@gmail.com> wrote: > > OK I see what you're saying. I agree with you in that auto > documentation usually sucks. What I'm wanting to do is remove all the > reference stuff and move it into it's own section so that the topical > documentation can be more specialized and concise. > > There are three types of users of django: Beginners, intermediate, and > experts. We should reorganize the documentation to target each type. > > Beginners who know programming and python well, but don't know Django. > These people will need the topical documentation the most because it > will explain to them the entire process from a birds eye perspective. > > Then there are the intermediate users, such as myself, who already > know how templates work, how urls are resolved, etc. We don't need the > topical documentation as much because we already know that stuff. What > we do need is reference. I don't know about you all, but I always have > to look up the model field parameters every time I write a model > because I can never remember them. Right now I have to load up this > page: > http://docs.djangoproject.com/en/1.2/ref/models/fields/#ref-models-fields > then wade through a ton of stuff because th stuff I'm looking for is > mixed with paragraphs and paragraphs of text. > > Then there are the experts. The core developers and the people who > delve in and modify django code itself. Doc strings and "#" > documentation should be written for them. Epydoc should be what these > people use. They already know what a bit of code does, what is > important to them, is how the code worlks. Why a certain under-the- > hood metaclass does what it does. It is surprising how what you propose in line with something was already discussed a couple of years ago and has been the general guideline in the documentation front work since then: http://groups.google.com/group/django-developers/browse_thread/thread/dcfaa00df58b6d3b As Luke says, what is still missing is to complete the addition/separation of reference material using the tools Sphinx give us, ideally reaching 100% of the public API reference. This is also documented in a TODO list: http://docs.djangoproject.com/en/1.2/internals/documentation/#todo (that would be the "documentation documentation" document you talk about) I'd suggest to go forward with you showcasing idea, choose one module that currently has no reference material, apply the strategy and share your results with this list. Regards, -- Ramiro Morales | http://rmorales.net -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-develop...@googlegroups.com. To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
