←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.259s | 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. 65 ◴[10 Oct 25 16:02 UTC] No.45540462[source]▶
I used to work on Drupal sites and they have very few examples for how to actually use various functions. So you'd run into instances where you're doing something completely wrong even if the function name makes sense.

The best documentation is type references and examples and a line explaining what the function does. Not one or the other.