Skip to main content
Removed meta-chatter about downvotes.
Source Link
jscs
  • 64k
  • 17
  • 134
  • 146

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

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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
  4. 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
  5. 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.

I'll be very surprised if
A. Anyone reads this
B. If they do they don't downvote instinctively

PROPOSAL OVERVIEW
Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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
  4. And now, for the part I expect most of the downvotes from, no one can edit or remove another person's example code
  5. 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!)

  • 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 @, 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.

Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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
  4. And now, for the part I expect most people to disagree with, no one can edit or remove another person's example code
  5. 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).



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.

deleted 41 characters in body
Source Link
MER
  • 1.5k
  • 7
  • 6

I'll be very surprised if
A. Anyone reads this
B. If they do they don't downvote instinctively

PROPOSAL OVERVIEW
Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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
  4. And now, for the part I expect most of the downvotes from, no one can edit or remove another person's example code
  5. 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!)

  • 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 @, learn from and decide for ourselves (as the programmer looking for example code) what is good and what isn't.



Anyway, it's a thoughthought, a potentially new one... for whichdespite that, I expect to be downvoted and marginalized but hope that someone might find it valuable.

I'll be very surprised if
A. Anyone reads this
B. If they do they don't downvote instinctively

PROPOSAL OVERVIEW
Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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
  4. And now, for the part I expect most of the downvotes from, no one can edit or remove another person's example code
  5. 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!)

  • 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 @, learn from and decide for ourselves (as the programmer looking for example code) what is good and what isn't.



Anyway, it's a though, a potentially new one... for which I expect to be downvoted and marginalized but hope that someone might find valuable.

I'll be very surprised if
A. Anyone reads this
B. If they do they don't downvote instinctively

PROPOSAL OVERVIEW
Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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
  4. And now, for the part I expect most of the downvotes from, no one can edit or remove another person's example code
  5. 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!)

  • 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 @, 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.

Tried to fix a few confusing things in what I originally wrote.
Source Link
MER
  • 1.5k
  • 7
  • 6

I'll be very surprised if
A. Anyone reads this
B. If they do they don't downvote instinctively

PROPOSAL OVERVIEW
Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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 theira 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
  4. And now, for the part I expect most of the downvotes from, no one can edit or remove another person's example code
  5. 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!)

  • 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.
    Functional programming, for example) while most people think it's horrible (tryexample; most of us 10programmers 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 @, learn from and decide for ourselves (as the programmer looking for example code) what is good and what isn't.



Anyway, it's a though, a potentially new one... for which I expect to be downvoted and marginalized but hope that someone might find valuable.

I'll be very surprised if
A. Anyone reads this
B. If they do they don't downvote instinctively

PROPOSAL OVERVIEW
Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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 their documentation item. 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
  4. And now, for the part I expect most of the downvotes from, no one can edit or remove another person's example code
  5. 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!)

  • 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) while most people think it's horrible (try most of us 10 years ago).
  • 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 @, learn from and decide for ourselves (as the programmer looking for example code) what is good and what isn't.



Anyway, it's a though, a potentially new one... for which I expect to be downvoted and marginalized but hope that someone might find valuable.

I'll be very surprised if
A. Anyone reads this
B. If they do they don't downvote instinctively

PROPOSAL OVERVIEW
Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. 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
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. 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
  4. And now, for the part I expect most of the downvotes from, no one can edit or remove another person's example code
  5. 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!)

  • 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 @, learn from and decide for ourselves (as the programmer looking for example code) what is good and what isn't.



Anyway, it's a though, a potentially new one... for which I expect to be downvoted and marginalized but hope that someone might find valuable.

accidentally posted the answer while typing :D
Source Link
MER
  • 1.5k
  • 7
  • 6
Loading
Source Link
MER
  • 1.5k
  • 7
  • 6
Loading