5 ms·

Really? In my experience, Django has about the best documentation of any open source web framework. How are the docs lacking? The site's focus is definitely dev

Really? In my experience, Django has about the best documentation of any open source web framework. How are the docs lacking? The site's focus is definitely developer-centric. It would be nice if there was either a broader focus on that site or an alternative entry port for non-developer folks--particularly non-technical decision makers.

tripzilch 14y ago
> Really? In my experience, Django has about the best documentation of any open source web framework. How are the docs lacking? It's been a few years so I don't recall exactly (and maybe it has improved) but I just found myself browsing and clicking around to re-read particular chapters all the time, that I could only reach via an unintuitive sequence of 2 or 3 clicks. Only when I found that the docstrings inside Django's code, plus the function signatures and the (IMO very well-written) code itself, were much more useful--as long as you have an IDE that allows one to ctrl-click an identifier to jump to its definition (cross-file/module), only then I got a better grasp on what Django was doing and how it worked. But then, that's the general take I got from Django after using it for some time: As long as you strictly stay within the "batteries included", it's absolutely great, and the documentation is probably wonderful and sufficient. But as soon as you need to develop your own `ImageFileWithMultipleSizesThumbnailAndExtraCheeseField`, you really need to dive into the innards of the code, the documentation starts lacking, and it's like they never even considered that sometimes your customers prefer their database fields with extra cheese. Hey but I'm not here to bash Django, it's a great framework (and so is Rails, btw). It's just that next time when I need something like it, I'm going to try and use one of those WSGI things with SQLAlchemy and see how that works for me. I'll probably really miss the automatic admin though.
- krelian 14y ago
  >I just found myself browsing and clicking around to re-read particular chapters all the time, that I could only reach via an unintuitive sequence of 2 or 3 clicks. It's true that the main documentation link doesn't have everything. If you want everything you need to go to https://docs.djangoproject.com/en/1.4/contents/ https://docs.djangoproject.com/en/1.4/contents/
- rikthevik 14y ago
  Yeah, when you start digging into Django, there's just no substitute for a good IDE (PyCharm for me) that lets you dive into the source. The source never lies. :)
kaolinite 14y ago
I agree, best documentation of any framework I've used.
boothead 14y ago
I'd say that used to be true for me but the pyramid guys have raised the bar when it comes to docs in the last few years - they're simply fantastic!

tripzilch 14y ago

> Really? In my experience, Django has about the best documentation of any open source web framework. How are the docs lacking? It's been a few years so I don't recall exactly (and maybe it has improved) but I just found myself browsing and clicking around to re-read particular chapters all the time, that I could only reach via an unintuitive sequence of 2 or 3 clicks. Only when I found that the docstrings inside Django's code, plus the function signatures and the (IMO very well-written) code itself, were much more useful--as long as you have an IDE that allows one to ctrl-click an identifier to jump to its definition (cross-file/module), only then I got a better grasp on what Django was doing and how it worked. But then, that's the general take I got from Django after using it for some time: As long as you strictly stay within the "batteries included", it's absolutely great, and the documentation is probably wonderful and sufficient. But as soon as you need to develop your own `ImageFileWithMultipleSizesThumbnailAndExtraCheeseField`, you really need to dive into the innards of the code, the documentation starts lacking, and it's like they never even considered that sometimes your customers prefer their database fields with extra cheese. Hey but I'm not here to bash Django, it's a great framework (and so is Rails, btw). It's just that next time when I need something like it, I'm going to try and use one of those WSGI things with SQLAlchemy and see how that works for me. I'll probably really miss the automatic admin though.

krelian 14y ago
>I just found myself browsing and clicking around to re-read particular chapters all the time, that I could only reach via an unintuitive sequence of 2 or 3 clicks. It's true that the main documentation link doesn't have everything. If you want everything you need to go to https://docs.djangoproject.com/en/1.4/contents/ https://docs.djangoproject.com/en/1.4/contents/
rikthevik 14y ago
Yeah, when you start digging into Django, there's just no substitute for a good IDE (PyCharm for me) that lets you dive into the source. The source never lies. :)

kaolinite 14y ago

I agree, best documentation of any framework I've used.

boothead 14y ago

I'd say that used to be true for me but the pyramid guys have raised the bar when it comes to docs in the last few years - they're simply fantastic!