I'm talking about this: http://stackoverflow.com/documentation/django
Compared to well written documentation, this kind of documentation is pretty bad. Yes, many projects have terrible documentation, and for them it might be an improvement, but for many that have good docs, this is a major step backwards.
Good documentation requires serious effort and organisation. It can't be achieved by throwing together lots of examples.
I agree that examples are important. That is why Django docs include examples, as well as reference docs, and topic guides and tutorials - a suite of different kinds and all linked together, so you can go from one to the other. With Stackoverflow docs, you just get a big collection of examples.
Take for example "Templates". This is a big topic. There is the process of loading and rendering a template, and the shortcuts you would normally take from a view. There is the Django template language itself, both the builtin functionality and how to extend it, the configuration required and understanding where templates are rendered from. there is the possibility of multiple template engines etc. etc.
Django's templates docs link you to all the different things you might want to do, including example based tutorials etc.
There is no way that the Stackoverflow docs are going to match that. The current examples are fine - if you already have everything set up and know where to put all the files, for example. Which will you will do if you've gone through the Django tutorials, which also render the Stackoverflow docs redundant.
Further, what is going to happen when things change? Django's docs are carefully versioned - after all, you might need old docs. The same care will never be achieved by Stackoverflow. When Stackoverflow docs have lots of incorrect and even insecure code in their examples, which are nonetheless upvoted, will Stackoverflow take responsibility for all the consequences, given they are going out of their way to provide an alternative source of documentation?
There is also the question of the usefulness of an examples based approach to coding. It is well know to lead to Cargo cult programming. A better approach is to have some examples to get you going, and then to understand what you are actually doing, so that you can put together the provided pieces to achieve what you need. An example to cover everything you might want to do is exactly what we don't want.
The approach the Django's docs take is far superior, and it is not an improvement to have an example for every variation.
Why does it matter? Why not just let Stackoverflow be an alternate resource?
Because:
- they have enough Google juice to divert searches away from the good docs at docs.djangoproject.com
- the reputation system rewards people for contributing there, and the ease with which you can add (low quality) docs makes it far more tempting than contributing to the official docs.
- the proliferation of poor quality docs will suck further time away from Django community - as we now have to cope with correcting people who have been misled by these docs - or be tempted to correct them ourselves.
Django docs are not perfect, by any means. And yes, contributing to Django docs has a higher entry barrier. It would be good if that barrier could be reduced -but often it is not an artificial one, but a necessary consequence of the fact that writing good docs is hard. For example, there is some markup to learn. That's because we want to be able to hyperlink everything together properly, so we need custom Sphinx markup, for example.
Are you serious about helping write Django docs? Then contribute to the official ones - or first tackle the problem of removing unnecessary barriers to contribution (the Django docs website itself is also open to contributions - https://github.com/django/djangoproject.com). The overall situation is not going to be improved by diverting resources away from that serious effort.
I agree, at first I tried filling up some fringe tags such as "algorithm", but in the end I think it will be for naught.
You brought up a very good point, about the barrier to entry. In all honesty, I'm not convinced that explicitly working for a low barrier to entry is all too desirable but if that is the goal then I think the most important part is reducing the effort it takes to find the location in the source tree where one should perform those edits.
This is why my blog posts link to the associated Markdown/reStructuredText documents directly.
With respect to SO Documentation, the flat hierarchy of content for each tag is what will ultimately make it a poor substitute for good official documentation.
For projects with poor documentation then yes, this is a substantial improvement but for the first few weeks we will just see people porting official docs onto SO. And whenever the official docs change, the SO content will attempt to mirror that. Hello maintenance burden. This is primarily caused by the reputation system I think.
This is the gold rush of SO reputation, hurry to document the low hanging fruit of JavaScript and rake in reputation passively from here on out...