←back to thread

Examples are the best documentation

(rakhim.exotext.com)
396 points Bogdanp | 1 comments | 09 Oct 25 19:34 UTC | HN request time: 0.212s | 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 #
golyi ◴[10 Oct 25 07:22 UTC] No.45536180[source]▶
They're not mutually exclusive you know, you can have both example and a proper technical doc.
replies(1): >>45536764 #
1. _0ffh ◴[10 Oct 25 09:13 UTC] No.45536764[source]▶
Took the words right outta my mouth!

Of course we want a full list of public functions with all the info. But with just a list of functions it's often still not quite clear how you're supposed to setup and call them, unless you dig through the whole list and try to understand how they interact internally. A few short examples on "How do I init the library/framework so I can start using it", "How do I recover from a failure case", etc. makes the docs infinitely more accessible and useful!