I have this in a script: `curl cheat.sh/"$1"`
I learned recently that tldr also has separate pages for subcommands.
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/
Ultimately, creating a small example that I know should've worked and changing things in a way that I could narrow down the problem worked best.
The point to all this is that examples often encapsulate multiple things into a condensed format, that is extremely high fidelity (since it's typically a code example that runs and has output). Things like Api documentation in comparison typically cover a huge surface area, and have way less effort in maintaining them.
Also for the record, I absolutely don't trust libraries on behavior that isn't extremely obvious, explicit and so absolute that it's almost effortless to find out (I am talking first thing on README, entire sections showing that one thing, or definition through types). I just assume that things like behavior around status codes are going to change, and do my best in the calling code to mitigate issues as much as possible.
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.
Of course we want a full list of public functions with all the info. But with just a list of functions it's often still not quite clear how you're supposed to setup and call them, unless you dig through the whole list and try to understand how they interact internally. A few short examples on "How do I init the library/framework so I can start using it", "How do I recover from a failure case", etc. makes the docs infinitely more accessible and useful!
That's exactly what I'm pointing to in the post:
>When jumping between projects, languages and frameworks, it takes a considerable amount of mental energy to restore the context and understand what is going on.
Examples let you grasp immediately how to use the library and provide you good starting point for your integration.
Detailed explanation of all params and configurations allows you to solve more complex problems and understand the full capabilities of the tool.
I am miserable when any of the two kind of documentation is missing.
The only exceptions are very simple libraries, where the example tells you already everything there is to know.
When feasible, I'd add repl environments. The ability to quickly modify and test the example can make up for a lot of the shortcomings documentation might have.
Even better are the challenges at the end of their examples which force you to rethink what you just read.
In particular, I don't want to have to learn half a dozen footguns because of a leaky abstraction.
You can intuit all you want from a method signature, and then you will fail to produce working code because you missed a config, or a preparation step, or don't understand how to process the results, or...
This means so long as you run the tests before shipping you basically can't ship with examples you forgot to update after an API change because they either don't compile or don't work.
And you might think well, nobody would ship examples that don't even compile right? But on more than one occasions I've used a Microsoft C# library that comes with examples clearly hand made by their engineers (yes I'm that old that it couldn't be LLM output) without checking they work. Somebody has sketched out what ought to work, they haven't tested it, and a reviewer has seen that it looks right and OK'd it, but again, never tested that it works. This is extremely frustrating because the documentation is wrong but now what?
I am tired of rudimentary docs that only have examples.
If I at least have some examples to get me started, then I can go digging through other documentation (or even just the code) to figure how to do more advanced things... but being unable to even get started is a much bigger frustration IMO.
One time my company paid $5k for a commercial x264 license, and when we asked for some documentation on how to get started with encoding some video frames using their C API, they simply responded "the code is the documentation." With no real examples to go on (at the time in the 2000s there actually wasn't much available online at all), this set me back a good two weeks that I felt was completely unnecessary and completely turned me off to interacting with them at all for the future.
We ended up switching to a hardware solution that was much easier, faster, well-documented, and way friendlier people to talk to.
I agree that automatically generated API docs from code is nearly useless.
I agree that examples are important and useful.
But examples are not "the best documentation." Or I should say hyperbole is poor documentation of one's point of view.
https://news.ycombinator.com/item?id=15779382
As the above 8y old discussion and today’s blog post both say: yes, examples are but one part of a complete set of learning materials — practicals, theory, recipes, reference.
However, in a toss up, the greatest of these is the one you always want first: picking the thing up, tossing it about to get a feel of it, and getting your hands dirty!
For code, worked examples are particularly helpful because your dev environment can jump to the function definition, which typically has its own reference documentation.
It has a pro over documented examples in that they are _guaranteed_ to be correct.
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.
If the audience is teammates, the _code_ itself is usually the best documentation.
Tests lie about edge cases. A test _might_ be demonstrating an edge case, or the suite might ignore large sections of edge cases.
Documentation is worse, it rarely documents edge cases. Country Y passes legislation and you need to implement it? Yeah, the docs aren't getting updated.
If your audience is a different team, API references (the headers/RPC message schema/javadoc/etc.) are better than written docs. Again, they are less likely to mislead you and are much more likely to work.
Unless, of course, the interfaces are telling fibs about what is allowed. Interfaces that are big buckets of parameters can do that.
Only if your audience is an external organization would documentation be a good primary reference. It meets them where they are, selling them on the capabilities of the software and bootstrapping them to the code.