I find it some of the hardest documentation (close to AWS) to understand the best way to do something. I think it's great if you know what you're doing or you have a rough idea of what to do but need more information, but for someone new to the framework it makes me want to paper cut the webs of my fingers and bath my hands in vinegar because it would be less painful.

This is the first time I have ever heard anyone talk ill of the django docs. I've been using django for at least 8 years now, and I had only been using python for a year or two at that point. The tutorial really brings you up to speed on all the basic concepts, and everything has a reference with examples. What projects do you think have better documentation?

Now that I really think about it, one annoyance I have with the django docs, is that they don't show you the import path for the modules used in examples. Though it's usually just 30 seconds of searching to find it.

I agree. The tutorial is incredibly simplistic with a "go play" ending. Then the actual documentation assumes you have a pretty good knowledge of how everything works. There is no middle step without utilizing 3rd party docs.

There are also lengthy guides on each part ORM, Templates, etc.

The problem is they quite frankly suck.

The official ones are incredibly dry and not approachable by someone wanting to get started and do anything meaningful. I've helped people learn Django and the official docs/guides are the last on the list of recommendations. there are so many better resources to look at first. I've told people to skip the polls app and go through Django girls tutorial. The polls app is a waste of time.

May be the django book might be the approach you are looking for...

https://djangobook.com/the-django-book/

I can relate. Beyond the very basics, there's a lot of 'what' but not so much 'how', especially when it comes to combining pieces. Often when I have a hard time to achieve something, I don't know if it needs to be that hard or I'm just trying the wrong way. The code doesn't help much with that, because without a lot of experience, it's a maze. Everything is connected to everything, due to the nature of the framework. Either you need to understand it all, or you end up fighting it. I really want to like Django, but every time it's the same story. Nowadays I prefer frameworks and specialized libraries that are much lighter. Even if the documentation is more limited, I also need significantly less of it. Perhaps I'm doing more work than strictly necessary, but at least I feel in control. I'd much rather go slower and see where I'm going than quickly down a road that ultimately turns out to be a dead end. Django is reasonable good for beginners and great for experts. Being neither, it frustrates me.

Do you have any specific examples? I'm sure the Django Project would be keen on improving the docs if they know why they're bad

I used to be a Perl dev for years, and tried a couple of Perl frameworks. I switched to Python because the docs were so much easier to get started with.

There are a lot of concepts to understand with a framework so my guess is that's actually your problem, but as far as documentation goes, Django's is pretty good.

How the fuck was any of Pythons docs better than Perl’s? ??????????

Docs, error messages etc are WAY superior in Perl. Idiot.

Django's docs were better than Catalysts (I would agree with you that python's docs aren't great).

Catalyst being Perl had more than one way to do everything, to the point that i couldn't actually work out what the framework was other than the URL router. Django had a far more sane approach which would seem to be needed if its your first time venturing into a web framework.

Could we please keep the discussion factual instead of resorting to name calling?

Not trying to sound overly-pedantic, but have you tried reading them? Not skimming them. Reading them start to finish. One line at a time, in order.

Try it. You'll understand what we mean when we say they're good.

Have you seen GCP's docs? They're far worse than AWS'.

I vastly prefer Flask's documentation (http://flask.pocoo.org/docs/). It explains everything from a perspective of what your use case would be, and they've gone above and beyond in covering use cases that might otherwise have been deemed outside their scope.

I really like flask's documentation, too. But somehow the explanation of blueprints didn't work for me, even after reading it several times.