[LeonB]

I like the example based approach. I learn from examples far quicker than I learn from “explanations”. If I attempt to learn from an example and my brain hits an exception, only then do I start reading the supporting text.

Nice approach. You’ve made a valuable thing and implemented a powerful idea.

[ehsankia]

I honestly wish a lot more documentations started like that with a bunch of examples. I think one I really enjoyed recently was attrs [0].

[0] https://www.attrs.org/en/stable/examples.html

[kmundnic]

I've been using tldr [1] instead of man pages lately to get started with a command (or to remind myself how to use one). I've learned a lot just by reading the examples shown, and then read the man pages if I am missing something.

[1] https://github.com/tldr-pages/tldr

[seph-reed]

Examples being greater than explanations is one of the main reasons I emphasize explanative error messaging, clear simple typings, and verbose function/variable names over documentation.

Docs are really good for discovery and should cover many topics shallowly so you can glean a big picture quickly. I generally don't like going to them for specs that could have just been an error message, a type, or a better naming convention.