On Tue, Feb 8, 2011 at 5:50 AM, Aryeh Leib Taurog <v...@aryehleib.com> wrote: > On Feb 7, 10:29 pm, anastasia <a...@anastasiacheetham.ca> wrote: > > Disclaimer: I'm not really responsible for django documentation, but > have poked at it a bit, and am somewhat familiar with the platforms.
For the record, I *am* responsible for Django's documentation, and most of the answers provided by Aryeh are correct. A couple of minor clarifications: >> - What did you like about your platform? What are its weaknesses? > > * growing in popularity and is used by many projects (See > http://readthedocs.org/) > * python based > * can output many different formats including html, windows chm, latex/ > pdf I would also add: Easily writable and readable by humans without extensive tool support. It's a very lightweight markup format, and the source is almost as readable as the final product. >> - Do you use any form of auto-generated API documentation? If so, how >> to you manage integration with more narrative text such as tutorials, >> examples, etc? > > I don't believe that django does, but sphinx is capable of this. > See the matplotlib documentation, for example. I believe the api docs > are auto-generated. > > http://matplotlib.sourceforge.net/api/index.html Django doesn't have autogenerated API docs -- mostly (IMHO) because this is a feature of Python itself -- anything that could be automatically generated could also be determined using the interactive prompt. >> - Are developers involved in writing the documentation, or is that >> left to technical writers? > > Seems to me the developers do it. Correct, although: * We have a couple of committers whose sole responsibility is to maintain the documentation * Several of our core committers, including our two BDFLs have formal training in the arts; Adrian is a Journalism major, and Jacob is an American Literature major. We also have a Philosophy major and three doctorates in our team. Overall, the "developers" are a literate bunch, not just a bunch of hackers forced to write some docs. >> - Do you support community input/editing of documentation? Why or why >> not? > > Seems to me that documentation is treated same as code. Those who > have commit rights commit; the rest of us submit patches. Correct -- as for the reasoning behind this: our experience has been that wikis become a wasteland. Good documentation, like good design, isn't something that can be arrived at by committee, or by consensus -- it requires strong decision making and editorial 'taste' to build a coherent and useful body of documentation. However, we are exploring some ways to make it easier for people to contribute suggestions and modifications to the documentation. Yours, Russ Magee %-) -- You received this message because you are subscribed to the Google Groups "Django users" group. To post to this group, send email to django-users@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.
