I'll be very surprised if
A. Anyone reads this
B. If they do they don't downvote instinctively
PROPOSAL OVERVIEW
TryTry a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details
- Create documentation that consists solely of two things
1-A stated problem/purpose/use case for which code is needed or designed to fit
2-Example code to match that use case - Anyone can create a stated problem/purpose/use case (a documentation item for short)
- These documentation items are created much like SO questions now... with a few differences:
1- It is completely fine & expected for someone to provide an example for a documentation item they created.
2- a slightly different, but very similar, documentation item would only be considered a duplicate in the instance that it is really the exact same documentation item but worded differently, but if there are nuances to the second, very similar, documentation item then it would not be considered a dupe - And now, for the part I expect most of the downvotes frompeople to disagree with, no one can edit or remove another person's example code
- Finally, there would be voting on documentation items and voting on examples as normal for stack exchange sites (minus the focus on things being similar automatically being seen as dupes).
READ HERE BEFORE FLIPPANT &/OR REACTIVE DOWNVOTING!! (PLEASE!)Some points of clarification:
- There really is a lot of good documentation around the internet, really there is. It could even be argued that standard Stack Exchange sites are some of the better forms of it.
- While there is a lot of good documentation it could be said that there are also many different views on what good CODE is. If I could remember who said it I'd link it here but it's been said that any programmer seeing either their old code or someone else's will automatically think it's bad and want to change it. THIS is what we are fighting with this documentation with examples... human nature.
- By not allowing the examples to be changed but only downvoted or upvoted, we don't lose the perspective of someone who may have a very good methodology.
Functional programming, for example; most programmers ten years ago would likely have seen any code leaning toward functional programming as horrible code, now many see it as an advancement, despite the fact that it's not new. - Regardless of what we all think, we are all right sometimes and wrong sometimes... which means our old code is probably not as bad as we think, and neither is fred's code that we had to take over...
- Finally, this would be the only way I can see a NEW service to add value to documentation. It would become a library of examples to look @at, learn from and decide for ourselves (as the programmer looking for example code) what is good and what isn't.
Anyway, it's a thought, a potentially new one... despite that, I hope someone might find it valuable.