←back to thread

Examples are the best documentation

(rakhim.exotext.com)
401 points Bogdanp | 1 comments | 09 Oct 25 19:34 UTC | HN request time: 0.215s | source
Show context
theamk ◴[09 Oct 25 21:31 UTC] No.45533317[source]▶
Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list.

Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? How do I pass in content-type? Does raise_for_status ignore 204?

Both have their merits, but if developer only has time for one, I'd go for proper doc.

[0] https://requests.readthedocs.io/en/latest/user/quickstart/

replies(8): >>45534019 #>>45535215 #>>45535253 #>>45535369 #>>45535610 #>>45535847 #>>45536180 #>>45538163 #
1. abacadaba ◴[10 Oct 25 12:23 UTC] No.45538163[source]▶
Unfair example google has the worst docs in existence. Either a quickstart with one uselessly simplistic example or an autogenerated class list on a totally separate site with no explanations to be found. Often I just end up looking at their libraries source code to learn how to use it.