2

I've been thinking of writing a documentation example which's purpose is to prove/confirm a certain statement, but I'm unsure if this is considered "acceptable" (even after reading the FAQ) or is what the examples should be used for.

Basically what I'm talking about are these kinds of examples:

  • Why X is/isn't required to perform Y
  • Why X should be used instead of Y
  • Why X should/shouldn't be used...
    • ...at all
    • ...in the case of Y
  • (and so on)

The first one is what my specific example would be about at the moment, but I'm curious about the others too...

So: Is it acceptable to write these kinds of documentation examples, or is there a better way of proving a statement or providing a good point?


EDIT:

In addition to the above, is it considered acceptable to include code from Microsoft's Reference Source in order to prove your point?

4
  • 6
    The questions you show have the smell of opinion-based question. Are we turning Documentation into some sort of platform where things that are matter of opinion should be "documented"?
    – Louis
    Jan 17, 2017 at 19:41
  • @Louis : Good point. Perhaps not, however I feel my specific example would fit much better in the documentation than as a self-answered question... Jan 17, 2017 at 19:45
  • @Louis : It is also to be mentioned that the specific topic of my example has been discussed by different people, but no one has really been able to point to any specific facts. That's why I thought I'd share the actual truth in an example. Jan 17, 2017 at 19:51
  • 1
    I've been trying to think of a case where Documentation would be better than a self-answered question. I've been unable to come up with one. This doesn't look like one to me, either. Jan 18, 2017 at 6:36

0

Browse other questions tagged .