2 ms·
If a library/framework doesn't provide samples/examples, then it's probably not a good library. "RTFM" isn't a valid answer anymore, unless you're being paid f
by jokoon 5y ago
If a library/framework doesn't provide samples/examples, then it's probably not a good library.
"RTFM" isn't a valid answer anymore, unless you're being paid for very meticulous software development, with high end precision software, which rarely happens. And in this case, you generally just read the code, not the documentation.
It's not a coincidence that code is written in a language, it's because it's meant to be self explanatory.
Documentation is relevant for engineering products, electronics, mechanics, etc, but I think I believe that software doesn't need documentation; only the code is required. Documentation should be written as code samples, and that's it.
I really think that software has been inflated and put on a pedestal as something only smart people can work with. It's not. Everyone who works in STEM, or the 25% of the most educated people, should be able to write some python.
- has_many_books 5y ago> I really think that software has been inflated and put on a pedestal as something only smart people can work with. It's not. Totally agree: that's the other website from us that didn't make it to Hacker News today https://dayofcode.co.uk https://dayofcode.co.uk
- zhdc1 5y agoI don't know if it's enough to simply provide example scripts and leave users to their own devices - even well documented code takes a while to understand. The best documentation I've seen is usually relatively easy to grok, includes example code for real-life use cases, and come with simple explanations.
- shantnutiwari 5y ago>> If a library/framework doesn't provide samples/examples, then it's probably not a good library Great point, and I'll add: The examples must cover the 80/20 rule -- 80% of the time, people just need simple examples just to get started. And the simple thing is important-- the examples must be standalone. I can't remember the number of times I just wanted to try out a new library, but couldnt even get the "hello world" version working, and just quit. It's harder if the library/code is in a language you dont use for your day to day job.