Examples are the best documentation
rakhim.exotext.com
Examples are the best documentation
1–10 of 179 posts
Re: Examples are the best documentation
#2Code examples can be executed as unit tests to prevent documentation regressions / bitrot in ways human language can't
Re: Examples are the best documentation
#3Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list.
Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? How do I pass in content-type? Does raise_for_status ignore 204?
Both have their merits, but if developer only has time for one, I'd go for proper doc.
[0] https://requests.readthedocs.io/en/latest/user/quickstart/
Re: Examples are the best documentation
#4also unit tests
Re: Examples are the best documentation
#5This is why LLMs won.
Useless documentation means half-arsed is better.
The world of IT is broken, what sort of idiot gives Linux to their parents when as a trained developer man is so useless?
It's just excuse after excuse. Unit tests are documentation sort of garbage.
That's what's mind blowing about LLMs, IT devs are so bad LLMs are better. Hacker News comments also confirm this.
Re: Examples are the best documentation
#6Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list. Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? H…
[dead]
Re: Examples are the best documentation
#7This is why LLMs won. Useless documentation means half-arsed is better. The world of IT is broken, what sort of idiot gives Linux to their parents when as a trained developer man is so useless? It's just excuse after excuse. Unit tests are documentation sort of garbage. That's what's mind blowing about LLMs, IT devs are so bad LLMs are better. Hacker News comments also confirm this.
[dead]
Re: Examples are the best documentation
#8Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list. Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? H…
Examples are often crucially valuable, not just for beginners. Some of them can inject in five seconds an understanding equivalent to an hour of reading the very-objective docs and experimenting. I'm thinking of some git doc pages. But it applies just as well to single functions that are very simple conceptually, but hard to describe clearly and briefly and completely.
The developer has time for neither or both. Once the productivity barrier for one has been broken, the other is a tiny extra effort. In that case, they must provide both, except in the small minority of cases that are exceptionally self-describing, where one (usually docs) is sufficient.
Re: Examples are the best documentation
#9Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list. Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? H…
Examples are often crucially valuable, not just for beginners. Some of them can inject in five seconds an understanding equivalent to an hour of reading the very-objective docs and experimenting. I'm thinking of some git doc pages. But it applies just as well to single functions that are very simple conceptually, but hard to describe clearly and briefly and completely. The developer has time for neither or both. Once…
[flagged]
Re: Examples are the best documentation
#10Examples are best only for the beginner/occasional users. For more experience devs, you want regular docs, with full parameter list. Case in point: requests. Google always drops me to the pages like Quickstart[0], which are full of examples. But they are useless for advanced users! Yes, even my limited brain can remember that you call "get" to issue HTTP GET. What other options does it take? Does it take a timeout? H…
I agree. Good documentation (nearly) fully specifies program behavior, and doing so with just examples is impractical or impossible.