On 11 January 2011 13:39, Christophe Pettus <x...@thebuild.com> wrote: > > On Jan 10, 2011, at 1:25 PM, Simon W wrote: > >> For such a good web framework it's a shame that the documention is not >> structured well .. at all. > > I have no doubt that the project would be more than receptive to doc patches > to fix the problem.
This isn't about patches to the existing docs (which are great for their purpose). It is about Django missing an API reference manual, something like .NET Class Library Reference (http://msdn.microsoft.com/en-us/library/gg145045.aspx), PHP's Function Reference (http://www.php.net/manual/en/funcref.php) or Java's (rather hideous looking) API reference (http://download.oracle.com/javase/6/docs/api/). I'm glad someone brought this up (although 'horrible' seems like too strong a word). I miss not having these docs in some online form because once you know enough about Django, you often know that Django has capability x but you don't remember what class/namespace it is in. You end up having to google and spend a while locating the info in the existing docs. Browsing or grepping the code isn't much better (maybe I'm missing an app or two here). API docs also tend to be more structured and concise so you can instantly see what parameters take what, what exceptions might be thrown, what the return value is/represents etc. Right now, I almost always have a browser tab open to code.djangoproject.com for this purpose. Talk/ideas are cheap, so here's my take on possible API docs for Django - An API reference site structured in a similar manner to the above examples, with the ability to easily search; integrated pydocs; links to relevant sections of the Django docs; a link to see the code of the function/class/method etc. A wiki-style section for each page would be nice too to document caveats, tips, tricks, relevant snippets etc. Of course the dynamic nature of the code makes this harder to do and will probably require some human intervention to ensure an entry exists for every parameter, mapped method etc. P.S. what's the short answer to why the current Django docs aren't on a wiki site instead of being versioned inside SVN? There are some minor clarifications here and there that I'd like to add, but the overhead of producing a patch, creating a ticket, flagging down a committer, getting a consensus, and finally having the patch committed is a bit off-putting. I can understand the process for code, but it just seems a bit over-the-top for docs. Maybe a compromise would be adding something like the per-paragraph comments that The Django Book site has; that way the docs stay official, yet there's still a way for users to add to them. > -- > -- Christophe Pettus > x...@thebuild.com > > -- > You received this message because you are subscribed to the Google Groups > "Django users" group. > To post to this group, send email to django-us...@googlegroups.com. > To unsubscribe from this group, send email to > django-users+unsubscr...@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/django-users?hl=en. > > -- You received this message because you are subscribed to the Google Groups "Django users" group. To post to this group, send email to django-us...@googlegroups.com. To unsubscribe from this group, send email to django-users+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-users?hl=en.
