3 ms·
Official Docs - best official project documentation I’ve read. It’s actually so good, that I never (well - almost never) bothered to look for anything else. All
by dgallagher 15y ago
Official Docs - best official project documentation I’ve read. It’s actually so good, that I never (well - almost never) bothered to look for anything else. All my questions were answered by the official documentation.
I have a different opinion. The Django docs are good, but not great. Here's how I see them right now:
- Combination of overview, how-to, and API reference.
Instead, I'd like to see it split up like so:
- Overview section.
- How-To section.
- API reference.
The overview section should cover general concepts. "This is what a View is, how it relates to URLConf, etc...".
The how-to section should show you how to do certain things. "Here's example code of how you can configure settings.py, how to handle an HTTPRequest in a view function, etc...".
The API reference, just a list of Django objects (showing inheritance), their attributes, functions, and parameters. Excellent example: http://api.rubyonrails.org/ http://api.rubyonrails.org/ . Currently some of this is documented, but some of it is only visible in source code.
Right now, everything in the Django docs is semi-bunched together. This made it really hard for me to initially learn the API; I'd imagine others' have similar issues. Since then I've gotten use to the docs, but it's still frustrating at times.
I do like Django very very much, but this is one of its pain points for me. It goes away with experience, but for new users it likely poses a bit of a challenge.
- jacobian 15y agoI completely agree -- as the docs have grown in size [] the organization has gotten worse. Originally I designed the structure to be similar to what you laid out, but things have gotten a bit out of control lately. We're workin' on it, though, so if you'd like to help out I'd really appreciate it! [] The length has nearly doubled in the last two years.
- dgallagher 15y agoThanks for clarifying things jacobian. :) I'd love to help out in a limited capacity (time constrained currently, unfortunately). In the past I've submitted tickets via the Django ticketing system indicating errors/clarification/what-not for the docs, but almost every ticket got flagged as spam and didn't get submitted. I kinda gave up after that point. Any suggestions on how to get tickets submitted? Oh, and one tiny feature request to the ticketing system: password reset. :)
- jacobian 15y agoSorry about the spam filter. We get a shitton of spam (I think we're the largest Trac instance anywhere) and it makes the spam filter rather paranoid. If you're signed in it shouldn't get triggered. Password reset is here: https://www.djangoproject.com/accounts/password/reset/ https://www.djangoproject.com/accounts/password/reset/
- dgallagher 15y agoAh cool, thanks so much! I'm not sure how customizable Trac is, but one idea would be to implement reCAPTCHA for anything marked as spam (assuming robots are causing spam issues and not users). If it gets solved, it's probably a human entering something on the other end. This is a Python 2 reCAPTCHA module I forked/updated: https://github.com/dave-gallagher/recaptcha-client-1.0.6-ssl https://github.com/dave-gallagher/recaptcha-client-1.0.6-ssl
- jacobian 15y agoWe've had that implemented since... I dunno, about six months ago maybe? (screenshot: https://skitch.com/jacobian/fgjmc/django https://skitch.com/jacobian/fgjmc/django). Not sure why you didn't see it. I wouldn't be surprised if Trac somehow didn't show it to you; it's a bit of a mystery to me some times.