E.g. the examples for the D standard-library's `curry` function are just unit-tests: the docs: <https://dlang.org/phobos/std_functional.html#quickindex.curr...>; the code: <https://github.com/dlang/phobos/blob/42b8c65ccfd35c863f7cedf...>
I realized at some point that a test and a how-to guide can and probably should actually be the same thing - not just for doctests (https://docs.python.org/3/library/doctest.html), but for every kind of test.
It's not only 2x quicker to combine writing a test with writing docs, the test part and the docs part reinforce the quality of each other:
* Tests are more easily understandable when you attach written context - the kind that is used when generating a readable how-to guide.
* How to docs are better if they come attached to a guarantee that they're tested, not out of date and not missing crucial details.
* Integration test driven development where how-to docs are created as a side effect is really nice.
As an example, in Elm (as in many languages) your publicly exposed functions in a package (a.k.a. library) are required to have documentation comments. This often includes a simple example because, well, it's easy to grasp. The build tool elm-verify-examples runs all of these examples and verifies that the output is what you say it is. It pretty cleverly uses the inline comment delimiter as the start of an arrow so that the rendered code listing in the example is still syntactically correct.
Software without good documentation pales in comparison to software with good documentation.
https://www.ramijames.com/thoughts/docs-deserve-more-respect
Then there's how much you need to test. Good tests go way beyond readable examples, they usually involve generating tons of tests with more or less random data and running them in a loop (property based tests). I do this, and to be honest I wouldn't recommend end users read them.
Automated property-based tests, fuzz tester cases, and similar things aren't documentation at all.