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.

Reply via email to