Both are needed for good documentation. You start with the details and then finish with a few examples so that someone who has read the details can check their understanding. Sometimes the example is all you need, but most often there are far more possible combinations of options such that an example of all the useful ones would be several books long (there is no good way to sort/index them so someone wouldn't find the example they need if you wrote them all). So you start with an explanation of each option, and then a few examples that are as different as you can make them so readers get a sense of what is possible and can look back to the explanation to figure out the changes they need to get the example to do what they need.

Good documentation is hard, and very rare these days.

Personally - what you're asking for is type definitions.

And it's a blurry line, since type definitions are a good form of documentation. It's just that type-system tooling has mostly replaced the need to go read through the docs for that. I expect to get it easily and obviously in whatever editor or IDE I've configured.

I think the prevalence of example based documentation is because of this trend - don't waste time manually writing the same thing type tooling is going to give your users anyway.

When I hit docs - I'm much less interested in the specific arguments, and I'm very interested in "Capabilities": Problems this tool can solve.

Examples are a great showcase for that. Especially if I have a specific problem in mind and I just want to know if a "tool" can solve that problem, and how to use it to do so.

---

If I have a type system: I want examples first.

If I don't have a type system: 1) I'm not happy. 2) I want examples first, followed by the detailed arguments/return/data structure docs you're referring to.

I don’t fully agree. Javadoc style documentation should be programmatic and driven by types and inline doc strings. It should just always exist and I would argue having it online is ok but why would not just go to the code itself.

Examples like QuickStart guides should absolutely be required. They serve as the quick entry point and general use of the library. If I only had the code docs I would have no idea how I am supposed to use the api and was my main complaint of many Java libraries historically as they only had a Javadoc.

I think this is almost provably true, for the simple reason that detailed technical documentation can be a substitute for examples, but the reverse isn't true.

1. If you want an example and the docs have an example, great.

2. If you want technical details and the docs have technical details, great.

3. If you want an example but the docs only have technical details, you can still get what you want by spending longer to read and understand the documentation. It's inefficient but it works. Third party examples are also frequently available.

4. If you want technical details but the docs only have examples, you're SOL. You have to hope that the code is available and readable, or just try stuff and hope it works. Third party technical details are rare.

Did you stop to consider that perhaps other people learn differently than you, and find examples as a way to soften the friction that context switching causes in a job?

I don't understand the resistance to examples being a part of documentation (and not a bonus).

There's a neat mental model that there are four kinds of documentation: tutorials, how-to guides, explanation, and reference.

I think that examples fit into the first or the second kind; I'm not too concerned which category they belong to, because the point is that all kinds all have their place.

Source: https://docs.divio.com/documentation-system/ - someone has already linked it in another comment, but I think it's worth replying because the comments in this thread are arguing about which kind they like the most.

To me, you're describing a specification, a type of documentation, with examples being another type. And I agree that a specification should just list definitions with explanations.

But there's no reason that a document cannot contain both a specification and examples. That's the type I prefer, and that's the type I mostly encounter nowadays. Usually a specification on the left with some examples on the right, maybe even interactive examples.

How about the Go style where examples in documentation are actually run as part of the test suite: https://go.dev/blog/examples ?

This way the examples must always be valid and runnable.

I think well commented examples are the best documentation but they are absolutely not a substitute for traditional docs.

I used to work on Drupal sites and they have very few examples for how to actually use various functions. So you'd run into instances where you're doing something completely wrong even if the function name makes sense.

The best documentation is type references and examples and a line explaining what the function does. Not one or the other.

https://en.cppreference.com/w/cpp/utility/optional.html Remove the examples and then make sense of _ANY_ of that documentation.

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.

The annoying part about Python is that searching for the python docs is hard.

E.g. "Python rstrip" (without quotes) in DuckDuckGo does not lead me to the Python docs on page 1.

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.

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.

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

>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.

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

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/

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.

I haven't had that problem. I just code something up, and poke around to understand some of the terms that it's talking about. Then I start reading about error return codes, why them happen, what kinds of parameters actually mean, etc. No examples are usually needed as long as documentation is complete

The most frustrating things are things that are undocumented at all and only have examples. What the hell kind of shitty documentation is just examples with no idea what parameters could or shouldn't be?!

I wholeheartedly agree, and would like to remind all man page authors that there’s even a conventional section named EXAMPLE. See man(1) for details. [0]

[0] https://www.man7.org/linux/man-pages/man1/man.1.html#DESCRIP...

Checkout cheat.sh

I have this in a script: `curl cheat.sh/"$1"`

I'm always pleasantly surprised that many man pages do have examples. But, sure, they could be a lot more comprehensive.

I liked it when Stackoverflow did something similar.

https://stackoverflow.com/documentation

We have shut down Stack Overflow Documentation. Documentation was our attempt at improving existing reference materials by focusing on examples. The beta ran from July 21st, 2016 until August 8th, 2017. For more details on why we ended it, please see our post on meta. Thank you to everyone that participated. As always, the content contributed by our community is available under CC BY-SA.

Totally agree but there is tldr for that.

I learned recently that tldr also has separate pages for subcommands.

It already exists - tldr. Use it side by side with man.

The state of man pages in the GNU + Linux ecosystem is just atrocious in general. You can thank the GNU Project for that. In sane man pages that actually care about quality, examples are specified where appropriate: https://man.openbsd.org/apropos.1#EXAMPLES

This. I do not know how many people are disappointed at their initial contact with Unix/Linux because they hit a complicated man page while trying to use a command

Agreed, examples and reference docs.

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.

I'm honestly surprised there are people who think that only examples are fine. And I'm equally surprised there are people who think only reference docs are fine. It's so infuriating coming across a project that only has one kind and not the other.

Absolutely! Examples (or 'tutorials') are just one quadrant of education about a system.

Not sure who came up with it first, but your link is similar to the author's link at the conclusion of the article:

> Since even major software projects rarely offer [4 distinct kinds of documentation][1], I am often hesitant to click on a "Documentation" link

Personally, I prefer documentation written as an explanation. If I understand how the thing works or why it's done that way, everything else is easy. Examples/tutorials/how-to guides only help me develop a conceptual framework by experiencing it, and I know that's how some people learn, but a skilled technical writer or educator can help me generate that conceptual framework correctly the first time.

I think the reason API references are so common is that they're really best suited for someone trying to build a wrapper or fully-compatible alternative implementation...which is what the original authors were doing, before the project existed. Many projects started as an internal, private API reference, and generating documentation can be as easy as making that public.

[1]: https://docs.divio.com/documentation-system/

I think conceptually diataxis is brilliant. However, it is not trivial to implement. Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective. The ratio also evolves with community adoption and expertise level. I really wish it was simply more actionable. Documentation is a hard problem, maybe we will figure out a better way one day. Until then docs will only be as good as the amount of time and expertise spent on them, which is usually not as high as it should be due to resource constraints.

This really should be at the top. It was almost frustrating seeing how much other discussion there was here before finally finding mention of Diátaxis.

Examples are crucial to documentation, but they aren't — at least in this view — a kind of documentation, so much as a technique for documenting.

I did a bunch of perl in the early-00s, then never touched it again until a random engagement in 2014. It came back IMMEDIATELY. Felt like having conversations with an old friend.

I don't know what it is, its definitely not mathematical purity or consistency, but there's something there witb Larry Wall's linguistics background and general attitude that just stays with you.

The examples in the Perl documentation are very well chosen, too. They aren't just a quick way to get up to speed. They aren't just code that you could use as a starting point and modify for your purposes.

Instead, many of them are almost like exercises to help you work through the ideas that the documentation is presenting. Some of them help you see how a syntax or other language rule applies. Sometimes the documentation presents two pieces of example code and walks you through why they're equivalent, helping you understand the language better. Or why they're almost equivalent and what the differences are.

In a lot of documentation, examples give you a superficial understanding but are a dead end if you want to go beyond superficial. In the Perl documentation, examples are often a bridge to a deeper understanding.

Unreal's lack of documentation is hugely frustrating and a massive time sink for me. They very much subscribe to a 'code is documentation' approach (I don't agree), but the 'screenshot of a node' documentation for blueprint is truly beyond parody.

> £JOB

Wait a second, do people use $ for `$job` because it's how they earn money and not, as I've always thought, used it as a variable name?

Stop throwing my entire world view out of order please.

But now with LLMs maybe they could begin to check for instance API documentation.