←back to thread

Examples are the best documentation

(rakhim.exotext.com)
407 points Bogdanp | 1 comments | 09 Oct 25 19:34 UTC | HN request time: 0.21s | source
Show context
satisfice ◴[10 Oct 25 04:09 UTC] No.45535297[source]▶
They are not the “best.” They are helpful.

I am tired of rudimentary docs that only have examples.

replies(2): >>45535362 #>>45537381 #
skinkestek ◴[10 Oct 25 10:54 UTC] No.45537381[source]▶
Given the choice between massive, "complete" documentation with no examples and decent but incomplete docs with good examples, I’ll pick the second every time.

Why? Because if you don’t explain how to actually use something, all the fine-grained details are pointless.

Classic example: try looking up the Java docs around 2003–2005 to figure out how to display an image in a Swing application. Endless pages about Graphics2D and Image and double buffering and what not but not a single mention of the real solution:

Just put it in a JLabel.

replies(1): >>45541460 #
1. badsectoracula ◴[10 Oct 25 17:27 UTC] No.45541460[source]▶
FWIW that stuff was put in the Java tutorial (not sure if this is still the case today). The "Visual Index to the Swing Components"[0] (a copy i found online from ~2003) shows JLabel with an image and the docs even begin with "With the JLabel class, you can display unselectable text and images.".

[0] https://fizyka.umk.pl/~jacek/docs/javatutorial/uiswing/compo...