Re:Examples Are the Best Documentation
by 1718627440 on Saturday October 11, 2025 @04:47AM
(#45547626)
> 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.
Re:Examples Are the Best Documentation
by 1718627440 on Saturday October 11, 2025 @08:11AM
(#45548535)
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.
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.