On 2011-01-11, at 07:44 , Sam Lai wrote: > 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/). > And what part of this can not be done by providing patches to the existing documentation to add apidoc extracts/refs?
> 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? Because wikis stink and a documented versioning means it's easy to keep in sync with the corresponding source, it's easy to package documentation with the corresponding release, documentation fixes can go through the same process as code fixes (including documentation bugs on the tracker) and documentation contributions are treated as first-class contributions and have the same status as code one, also serving as a "gateway drug" to contribution to Django's code? > 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. Only the first two are your job (why would you have to "flag down a committer"?) and unless your changes are extensive and/or controversial in my experience getting a document patch in is trivial. Which leaves three tasks: 1. editing the rst files, 2. running `svn diff` and 3. creating a ticket. Last time I did it, it was pretty painless. -- 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.
