On Tue, Jan 11, 2011 at 12:44 AM, Sam Lai <samuel....@gmail.com> wrote: > 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've already addressed this point politely, so perhaps it's time to turn it up a notch: If your computer is incapable of running pydoc, epydoc or other similar scripts, how is it simultaneously able to run Django? Or, not quite so snarkily: If your computer *is* capable of running pydoc, epydoc, etc., why aren't you using those tools? And if you're not using them now, why should I believe you'll make use of epydoc-generated API references if someone else generates them for you? (OK, so that was pretty snarky, but I think it's a valid question to ask) > 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's already a wiki on code.djangoproject.com; it's part of Trac. If you think wikified documentation would be a good idea, you should feel free to start putting some up there. What you'll find pretty quickly, though, is that there's a good reason why the official docs live in the repo and are maintained by the core team rather than being on a community-edited wiki: the wiki is where useful things go to die. It's full of half-baked solutions, code that only (maybe) runs on Django 0.96, etc., etc., because the nature of a wiki doesn't really encourage people to make long-term maintenance commitments. Those of us who have commit bits *have* made such commitments, and incidentally do a lot more than just committing documentation patches as they come in; for anything bigger than a typo fix, there's almost always heavy editing going on for style, consistency, readability and a bunch of other factors that a wiki can only manage at the cost of massive bureaucracy and high barrier to entry (it's no coincidence that Wikipedia is notoriously hard to edit successfully -- I'm pretty sure they have more documentation on policies than we have documentation, period). -- "Bureaucrat Conrad, you are technically correct -- the best kind of correct." -- 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.