Gregory's Server@mhoye This 100%!!
My god I can't believe how many times I've looked with despair at convoluted docs when a series of explained, code examples would have gone 1000x better.
That's why people love StackOverflow, because the answers usually include *example code*.
It's the programming equivalent of 'a picture is worth a thousand words'.
Show me don't tell me.
@syntaxseed @mhoye
I often suspect if the ultimate “zen” of documentation is just a well structured and indexed series of code examples with outputs and inputs.
Similarly for research papers except with figures and plots.