←back to thread

Examples are the best documentation

(rakhim.exotext.com)
409 points Bogdanp | 4 comments | 09 Oct 25 19:34 UTC | HN request time: 0.804s | source
Show context
harimau777 ◴[10 Oct 25 12:35 UTC] No.45538265[source]▶
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.

replies(12): >>45538587 #>>45539170 #>>45539306 #>>45539666 #>>45540462 #>>45540652 #>>45540922 #>>45541159 #>>45542376 #>>45543780 #>>45544276 #>>45544287 #
1. hatthew ◴[10 Oct 25 21:59 UTC] No.45544287[source]▶
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.

replies(1): >>45547626 #
2. 1718627440 ◴[11 Oct 25 08:47 UTC] No.45547626[source]▶
> 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.

replies(1): >>45548304 #
3. hatthew ◴[11 Oct 25 11:32 UTC] No.45548304[source]▶
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.
replies(1): >>45548535 #
4. 1718627440 ◴[11 Oct 25 12:11 UTC] No.45548535{3}[source]▶
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.