3 ms·
Documentation is frighteningly bad across the industry and nobody has a good solution yet other than hoping that someone else will do something about it. And i
by MattGaiser 7y ago
Documentation is frighteningly bad across the industry and nobody has a good solution yet other than hoping that someone else will do something about it.
And if you think Django is murky, try Spring :). Django is one of the easiest frameworks to work with simply because it includes so many functions you would otherwise need to somehow integrate. And even then there are still these issues.
Good post.
- bayesian_horse 7y agoI think Django's documentation is fantastic. 90% of the time I have to look up something, google redirects me there anyway.
- MattGaiser 7y agoDjango's documentation is great for developers who know their way around documentation like that as it is very comprehensive. It drills down nicely and is quick and easy to understand if you otherwise know what else is going on. What it misses is mapping that documentation to the specific problem a person wants to solve or the feature they want to build. When I was learning Django a couple years ago I found the examples and best practices sparse.
- jldugger 7y agoA long long time ago, there was a really great website called djangobook.com. It had like 20 chapters and projects explaining how things are done in Django, and each paragraph had a comments section where people could ask questions specific to that paragraph. That site probably did a lot for Django's success in the community. Unfortunately, giving away a free resource like that doesn't balance the books and years of neglect later the site no longer represented modern Django. It's entirely possible the new Django book site is just as good, but the paywall discourages novices and experts alike. My friends who stayed webdevs think Two Scoops of Django is close in scope, and comes with free updates. It's not quite the everbook that I had hoped the original site would be, but is highly focused on best practices.
- VBprogrammer 7y agoThe Two Scoops book is good but I found it difficult to read due to its extremely contrived examples. Maybe that is just me though.
- porker 7y agoNot just you. Also annoyed at their pricing model; I bought the original book, 3 months later it was out of date and "buy our updated copy" was their answer. I got no use out of it.
- collyw 7y agoCompared to what I have seen with React + React add ons its fantastic. ("2 Scoops of Django" is an excellent book to describe best practices. It's something I haven't seen the equivalent of elsewhere).
- Larrikin 7y agoI was so disappointed with other frameworks since Django was my first. I've come to realize this is widespread as I've learned other languages, but every time I start a new project and setting up the important boilerplate I'm constantly thinking in my head "Django would have just included this or there atleast be a battle tested plugin"
- MattGaiser 7y agoI think it depends on who you are as a dev. A lot want to create from scratch or have it be a handcrafted product, which I can respect. I just like producing cool stuff and don't want to be manually running SQL queries in both dev and prod.
- monsieurbanana 7y agoYour comment comes off as haughty to me, as if you were saying that if you choose not to use a framework like Django its because you want to have a "handcrafted product" and because you don't care about "producing cool stuff", which sounds like a textbook definition of a bad (unproductive) programmer. I assure you it's not, not using frameworks can also be a purely pragmatic choice. If you deviate from their intended use, they can very quickly become an annoyance instead of a time gainer.
- MattGaiser 7y agoI am thinking more about the people who reflexively use Flask as Django is "bloated."
- collyw 7y agoI never really got that unless people were complaining about Django's ORM. The framework is flexible enough that you can use as little or as much of it as you need.
- LifeIsBio 7y agoDjango has been a joy to work with. As other's have mentioned, I'm a huge fan of their documentation. I think they do a great job of letting you quickly hop between Tutorial and Reference docs. Lots of links help me quickly dive into more detail when I need, then jump back out.
- aserafini 7y agoIs there a better documented framework than Django? I am not aware of one.
- MattGaiser 7y agoMy original comment misses some nuance. Django's documentation is great for developers who know their way around documentation like that as it is very comprehensive. It drills down nicely and is quick and easy to understand if you otherwise know what else is going on. What it misses is mapping that documentation to the specific problem a person wants to solve or the feature they want to build. When I was learning Django a couple years ago I found the examples and best practices sparse.
- reroute1 7y agoDjango is a big framework, it isn't aimed at beginners.