The reason I chose django in the first place was the documentation. Compared to everything out there, it was incredible. Back then it also had a helpful comments section on each page where people chimed in to clarify various parts of the document. It reads like a text book, which is a big help when learning the framework.
Unfortunately it reads like a text book, which is a big pain when you know the story and just need the details. The wonderful code snippets lose their context. The lengthy explanations and sequential introduction of facts becomes more hinderence than help when trying to find that one bit you know is in there somewhere, but it's a needle in a haystack. It's designed for reading, not so much for reference. It's also definitely not for the impatient. After several years with Django, I usually find it easier to just poke around the source. It's all layed out logically and, and if you have a general overview of the framework it's much faster than trying to scan through the online docs. Unfortunately this approach requires a certain level of familiarity with how django works to get the most out of it. A few things I think would help make a big difference (they would have to me at least): 1) A couple of complete reference examples. Not just snippets introduced a few lines at a time, but full working examples you can unzip and expect to work and provide a simple reference to the basics. I've been using django for 3 years now in developing a fairly complex project. I'm still not 100% clear on the best way to layout a project. What I have obviously works, and I'm stuck with it now... but it was a guess back when I first started. I realize there is no one size fits all answer for that type of question, but a tiny working example with one project and two apps would go along way to providing someone first starting out, especially if the projects did simple introductions to all the major topics: a view, a view with an authentication decorator, a good example of template inheritance use to 'theme' a site, a few of forms, severa of which don't use a helper (ie no ModelForm) and requires some inter-field validation, maybe a simple middlware that reads/writes a cookie. A custom tag/filter or two. Something that showcases the "admin is not your app" principle. I really would love to do this, but I'm a little concerned it would turn out to be a bad example here and there! If there is interest I'd volunteer to give it a go though. 2) An overview of how django processes a request. From start to finish, concise on one page with links to the appropriate details if necessary. Possibly a paragraph or two explaining how it differs from say php. In my opinion this should be the first page of the documentation, well before the tutorial. The following page is ancient, but a good example of what I mean. It wasn't until I read it that everything just kinda clicked. Too bad it took a good 6 months for me to run across it more or less on accident. http://www.b-list.org/weblog/2006/jun/13/how-django-processes-request/ 3) The page comments for the existing documentation. I really miss that feature. The comment system PHP uses improves their documentation many times over. With Django's great community I'm sure we'd get a lot of good additions, though moderating the comments makes more work for someone. 4) A small 'best practices' reference not about the django details, but the big picture. Using virtualev. Project layout. Admin vs app. Considerations to keep in mind for writing reusable apps. Production vs Development configurations and switching. Handling timezone conversions. Avoiding performance pitfalls when using orm queries. Signals, how they can be useful. -- 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.
