I was under the impression that Documentation was geared towards self-contained, short and pragmatic examples, since often we learn something by first trying it.
However, prose seems to prevail and people start piling edits over edits, transforming what was quick to read into endless descriptions!
It seems that everyone wants to add their 2 cents, but what I thought would be a very simple and basic example becomes a monster overnight!
How do we convey/enforce the message that we want examples to be: try first, read about it later!?
Otherwise, I do not see how this is going to be better than searching Stack Overflow.
EDIT
I think my message is getting misinterpreted. I personally prefer concise explanations over a sentence that dishes out all of the details. Often these details are not relevant in every situation, so why not let another example explain the particular case?
I will give you an example in Matlab about the transpose operators. Tell me, would you like the big chunk of text before or after the examples? Also, is the paragraph concise and mostly relevant?
EDIT
It seems that quantity will dominate unless there is a change in the approach: Minimum tag score for adding documentation. The post raises a more generic concern and my question is just a specific manifestation of that problem.