←back to thread

Examples are the best documentation

(rakhim.exotext.com)
409 points Bogdanp | 1 comments | 09 Oct 25 19:34 UTC | HN request time: 0.2s | 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. kajkojednojajko ◴[10 Oct 25 21:59 UTC] No.45544276[source]▶
There's a neat mental model that there are four kinds of documentation: tutorials, how-to guides, explanation, and reference.

I think that examples fit into the first or the second kind; I'm not too concerned which category they belong to, because the point is that all kinds all have their place.

Source: https://docs.divio.com/documentation-system/ - someone has already linked it in another comment, but I think it's worth replying because the comments in this thread are arguing about which kind they like the most.