Examples are the best documentation

Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function.

Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I need to fix a problem or actually learn the library.

Also having examples is fine, but they should be considered a bonus; not documentation.

I think this is almost provably true, for the simple reason that detailed technical documentation can be a substitute for examples, but the reverse isn't true.

1. If you want an example and the docs have an example, great.

2. If you want technical details and the docs have technical details, great.

3. If you want an example but the docs only have technical details, you can still get what you want by spending longer to read and understand the documentation. It's inefficient but it works. Third party examples are also frequently available.

4. If you want technical details but the docs only have examples, you're SOL. You have to hope that the code is available and readable, or just try stuff and hope it works. Third party technical details are rare.

> It's inefficient but it works.

I'm not sure it's inefficient. It gives you the knowledge what is and isn't possible and also the semantics of what you actually do, all things you need to have later anyway. Relying only on examples is a great way to miss unintended side-effects or other consequences.