It bugs me already a long time. There's inconsistency in what is called "examples". In the documentation section I was originally willing to find many examples for some topic, because this is how things are called there - Topics & Examples. But we don't create alternative examples which we could upvote/downvote and choose from. We call the example that we create some "sub-topic" and it is exactly it - a sub-topic, containing 1 or 2 examples by the guy who created the subtopic under the "examples" section.
This opens problems. By creating an "example" we "occupy" that. There is no space for others to suggest their own alternative examples of the same sub-topic! I mean, if you create another example - that is duplicating, but that is the only way to receive feedback by votes! On the other hand, if you decide to edit the original "example" by posting your own code as an example - then you must decide where to put it, as the last example? or as the first (because you think your example is better)? or maybe to delete the original code example? Then you cannot receive feedback by up/down votes. So users of the Documentation are not always seeing the best examples of topics, simply because actual code examples are not up/down voted. Only the sub-topics (so-called examples) are voted on depending on their usefulness, basically. However, the actual examples within that sub-topic might not be clear enough.
Does anyone else see this inconsistency? What if we just rename the "example" to e.g. "sub-topic"?
Take a look at this, which I ran into recently (which I found useful, but it clearly illustrates my doubts about the structure/naming):
- within the "example" we see syntax, while there is also a separate place for syntax;
- within the "example" we see another example;
- there is only one actual example on this Convenience Functions sub-topic, which in some cases might not be good enough. It would be much easier to up/down vote alternative actual examples and not to start discussions over how to design a good example or unilaterally delete something.