Examples are the best documentation

Examples 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/

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.

Examples is for beginners. Beginners here refer to people that started to learn something, anything. But one you've got a conceptual understanding of the thing. You mostly need a full manual/reference.

I agree. Good documentation (nearly) fully specifies program behavior, and doing so with just examples is impractical or impossible.

It is order of magnitudes easier to understand behavior through examples than through a reference-like documentation. People suck at naming things, and then documenting them. Just today I spent the last few hours trying to figure out how to get something to work because a parameter only worked if another paramter had a specific value. There was too much magic to try and figure out the code, llms wrongfully told me the latest version doesnt support the parameter because it couldn't find any documentation.

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.

>occasional users

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.

A proper doc definitely has to provide the details. However starting with an example or two is a nice way to a give the users a quick overview. Even better when this example is interactive as for redis where you even have an example use case. See https://redis.io/docs/latest/commands/incr/

They're not mutually exclusive you know, you can have both example and a proper technical doc.

Took the words right outta my mouth!

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!

Unfair example google has the worst docs in existence. Either a quickstart with one uselessly simplistic example or an autogenerated class list on a totally separate site with no explanations to be found. Often I just end up looking at their libraries source code to learn how to use it.

Even as an "expert with several decades of experience" there are so many parts to a complex system that I still am a beginner in.

I’m not sure if that’s true.

The number of times I’ve opened FFmpegs man page must number in the hundreds. I think I’m a pretty good conceptually, but I can’t remember all the flags. IE that –s is frame size, while -fs is file size.

And while that man page does have some examples, these days I tend to ask an LLM (or if it’s going to be simple Google) for an example.

>Examples is for beginners.

No, not really, or I should say simple examples are for beginners.

Typically when I'm writing example pages I write it in

Simple example

Simple example

Simple example

Intermediate example

Intermediate example

Complex example.

Having complex examples can really help those that are looking at going beyond the basics.

That's why the recommended practice with shell usage is to write a script (or alias or function) and to use the long version of the flag in the script. Instead of having a complex invocation of ffmpeg, you'd have `flac2mp3 -q low file`.