4 ms·
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 a
by LeonB 6y ago
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 6y agoI 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 https://www.attrs.org/en/stable/examples.html
- kmundnic 6y agoI'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 https://github.com/tldr-pages/tldr
- seph-reed 6y agoExamples 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.