The current documentation model is focused on a set of arbitrarily defined topics, within which are examples.
I believe that this model has led to widespread confusion about what Docs.SO is for, and therefore widespread misuse of it. People are making topics and examples for things that we were probably not intended to document. In some cases, people are just copying&pasting stuff from existing documentation. In turn, this has led to people trying to clarify how it's supposed to work. Or just trying to establish it, since nobody seems to know.
Q&A is designed in terms of a "problem->solution" model. A person has a focused problem, and thus asks a question. People post answers which represent solutions to that problem.
But in the early days of SO, we had some problems with people expanding this model into more opinionated questions that did not represent problems to be solved. Eventually we clamped down on that, focusing the scope of the site, not really on Q&A, but on problems&solutions.
Docs.SO's model is topics and examples. But these concepts are so nebulous that everyone interprets them differently. Just like SO's early days of Q&A, people aren't really sure what a "topic" is.
I think a better model for truly code-focused documentation is not so much topic&examples, but task&examples.
Tasks are things that are bigger than Q&A's focused problems. These would be something like "string searching". That's not a focused problem, since there are a lot of cases of string searching, so it wouldn't work as a question. But as a task, it is much more reasonable.
You would have examples of various kinds of string searches: basic exact matching, regex searches, Unicode-based, case insensitive searching, and so forth. If there are commonly available libraries that can aid in searching, examples can be made for them too.
When you have task-focused documentation, voting on examples now makes sense. The examples are effectively competing with one another. Each one represents a complete solution through different approaches. And while different approaches may be valid, some are very much so better than others. The order of examples in a task is relevant only in how good those examples are at accomplishing that task.
So rather than documenting how regex works in a language, we would instead document the things you would use regex to do. But not in a "with regex" kind of way; we allow regex to be one possible example of dealing with that task. We focus on getting stuff done, not on the minutiae of syntax.
That would prevent us from getting involved in creating reference documentation. It would keep us focused on what we do well: solving things. Docs.SO should be generating cookbooks of usable code, not rebuilding reference manuals.
This would also solve one of my biggest issues with the current system: topics for which code examples cannot be provided. They simply would not exist, because there are no topics; there are only tasks. And tasks are things that have to be able to have code.
This answer from Kevin Montrose seems to agree with this point of view:
- The primary focus of Documentation is clear and concise examples.
- Examples should illustrate solutions to common problems and ways to accomplish common tasks
- Examples should be broader than the typical answer. Q&A still exists, after all.
- Syntax, Parameters, and Remarks support Examples
- they should reduce duplicate explanations
- they're optional because there isn't always duplication to reduce
If those are what examples are for, then collections of such examples are not "topics". They very much are "tasks". Tasks define what you want to do; examples show how to do it.
This answer from Oded also seems to support this view:
In general: SO Documentation is supposed to be a source of examples of how to achieve specific things in a said technology.
What we usually see in official documentation is a list of APIs without any explanation of how they are supposed to be used, how to achieve specific goals using them or any examples of usage.
Achieving specific goals? Like a task, right?