Comment by hatthew
4 days ago
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.
The first part of that line is "If you want an example...". If you want to learn about more advanced usage of some function, then you don't want an example, and that line doesn't apply to you.
What I say is that you think you want an example, but then either you come back later or you don't and ship slightly broken software.