←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.023s | 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. constant_flux ◴[10 Oct 25 16:20 UTC] No.45540652[source]▶
Did you stop to consider that perhaps other people learn differently than you, and find examples as a way to soften the friction that context switching causes in a job?

I don't understand the resistance to examples being a part of documentation (and not a bonus).

replies(3): >>45540812 #>>45544267 #>>45544777 #
2. shemtay ◴[10 Oct 25 16:35 UTC] No.45540812[source]▶
sometimes professionals need to fix shit and need exacting clarity
3. joemi ◴[10 Oct 25 21:58 UTC] No.45544267[source]▶
It shouldn't be an either/or situation. Good documentation should include both the API spec _and_ examples. I believe the person you're replying to was complaining about documentation that's _only_ examples since it seems like that's what TFA was advocating for.
4. KalMann ◴[10 Oct 25 22:57 UTC] No.45544777[source]▶
I think you're being unfair. The blog post claimed "Examples are the best documentation". If I use your own logic, shouldn't I say to the blog writer "Haven't you ever thought people learn differently from you?".

I think harimau777 was just expressing his opinion, like the blog owner.