Examples are the best documentation

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.

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.

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.

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.

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.

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

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

Checkout cheat.sh

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

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?!

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

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.

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

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

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.

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.

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

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

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.

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

No. Examples are there to show how to use this method, and other methods in conjunction.

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

Why rely on someone to intuit what you could just simply state explicitly? That sounds like you're just asking for trouble if someone doesn't think/intuit in exactly the same way that you do.

Personally I am much more tired of lengthy troves of API docs that, while fully specifying the system, do nothing to specify how one is actually supposed to use it in practice, such as the general flow of the program itself, which functions are relevant to what overall operations, in what order certain functions should be called relative to others, how one should handle errors, etc.

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.

Given the choice between massive, "complete" documentation with no examples and decent but incomplete docs with good examples, I’ll pick the second every time.

Why? Because if you don’t explain how to actually use something, all the fine-grained details are pointless.

Classic example: try looking up the Java docs around 2003–2005 to figure out how to display an image in a Swing application. Endless pages about Graphics2D and Image and double buffering and what not but not a single mention of the real solution:

Just put it in a JLabel.

Right, one of the best out-of-box tooling decisions for Rust is that by default, and out of the box cargo will assume all your documentation examples are tests it should compile and execute.

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 have at times looked at tests to get an idea of how the developer expected the code to be used.

> than workflow-type documentation.

Yes, for api/token interactions I love examples that show how to generate a token with only permissions for what you are doing. Then pulling said data from API and interacting with it. At least that's how the users that use the product I work on. Security, workflow, and cleanup are great examples.

The user model an API exposes and the internal model to implement this can be very different. It's like trying to conclude from the transformation a clockwork does, what it's purpose is (keeping track of time passing). The user model never needs to occur explicitly in the code.

I agree. When we moved to Python, I really missed all the examples that php had that the Python docs didn't.

Why not both? That way you can use the docs if you are learning the language AND if you already know the language but are looking for deep details.

Only if it's aware of your platform/programming language/etc

I’d say the part of the unit test that is helpful is the example of using the code.

It has a pro over documented examples in that they are _guaranteed_ to be correct.

The form the documentation takes depends on the audience.

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.