←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.002s | 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. snozolli ◴[10 Oct 25 16:58 UTC] No.45541103[source]▶
Everyone who disagrees with you are amateurs.

"No true Scotsman would want examples."

I'm far from an amateur and I want to see several concise examples in documentation. That doesn't mean that's all I want to see.

replies(1): >>45541633 #
2. sfn42 ◴[10 Oct 25 17:39 UTC] No.45541633[source]▶
That's not what anyone said. We both said examples are great. They're just not more important than proper API docs.

They're not the best. The best is thorough api docs. The rest is nice to have.

And I'm not no true scotsmaning, I'm just saying most devs are ass. I know, I see people with 20 years of experience on me write buggy trash code that I have to fix. I see people whine about the java docs as if they aren't some of the best damn docs available anywhere. Because they're ass and they can't properly use the tools they're given. They'd rather have examples and copy snippets from SO or have ChatGPT write it for them.

Any professional will appreciate proper documentation. It is literally impossible to create examples for every situation. Api docs, by their nature, cover all use cases because they simply describe what exists not how to use it. So for those of us with the knowledge and intelligence to actually just look at the parts and put them together on our own, ie professionals, API docs are king. Examples are useful sometime, API docs are useful all the time.

But of course if you don't even know the language well enough to read the documentation, you prefer examples.