My 2c (as a lowly Django user). Having used Another Large Web Framework (open source) for nearly 10 years, I can say with confidence that Django's human-written documentation is superb. The ALWF documentation was never kept up-to-date (and the online API did not really help much) - the user's had a wiki which attempted to fill that gap but ended up exactly as per Jame's comments: "the wiki is where useful things go to die. It's full of half-baked solutions, code that only (maybe) runs".
Maybe the Django project/development team is making an unreasonable assumption that people cannot generate the API using the appropriate Python tools... assuming enough people feel this way, there is nothing preventing any one of them from tackling this and putting it on a website for the rest to browse. If you have enough gumption to work with an open source project this should be readily "doable". On Jan 11, 9:55 am, James Bennett <ubernost...@gmail.com> wrote: > 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.
