←back to thread

Examples are the best documentation

(rakhim.exotext.com)
409 points Bogdanp | 2 comments | 09 Oct 25 19:34 UTC | HN request time: 0.569s | 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 #
sfn42 ◴[10 Oct 25 14:44 UTC] No.45539666[source]▶
This is the right answer. Everyone who disagrees with you are amateurs.

A Javadoc-esque API doc is the minimum requirement for a serious language/library. Examples and tutorials are nice too, but the API doc can be automatically generated in every serious language so not having it is just plain unacceptable.

Tutorials, articles and examples etc are fine too, they can be combined with the API doc like Java does. But that's gravy, on top. You don't have just gravy, it needs to be on top of something and that something is a proper API doc.

This isn't even a discussion in my mind, it's just the right way to do it. It's a solved problem. You optimize for power users not amateurs. 99% of the time when I look up docs what I need is a plain boring API doc, I only need examples in my first week.

replies(3): >>45540327 #>>45541103 #>>45544220 #
1. hatthew ◴[10 Oct 25 21:53 UTC] No.45544220[source]▶
I think it's a bit harsh to call everyone who disagrees amateur. However, anecdotally it doesn't feel very incorrect. When I do pair programming with less-experienced developers, I'll often watch them glance at the API docs, skim over the technical details, look at the example, copy paste it, and then be confused why it doesn't work. Then I pointedly suggest reading the specific paragraph that explains the confusion they have.
replies(1): >>45545454 #
2. sfn42 ◴[11 Oct 25 00:51 UTC] No.45545454[source]▶
Yeah, I'm not saying it to be mean I'm just calling it as I see it. Can't recall if it was the article or a comment or both, but someone mentioned that it's hard to understand API docs in some cases because it relies on understanding the language itself.

If you don't even know the language well enough to read docs I'd say you're an amateur. And if you're one of those people who just chronically don't read docs you're definitely an amateur. I mean you may have a job and you may even build stuff that kind of works, but unless you're sitting down and looking closely at the details you're not doing things right. You can't be. Doing things right requires looking closely at the details.

And I know from experience that there's a vast number of employed amateurs who write nothing but legacy code.