Examples Are the Best Documentation

Code examples can be executed as unit tests to prevent documentation regressions / bitrot in ways human language can't

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/

also unit tests

This is why LLMs won.

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.

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.

They are not the “best.” They are helpful.

I am tired of rudimentary docs that only have examples.

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.

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.

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.

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 often show the "spirit" of the invention it's intended usage if you like, which explains more what it does than name alone... also reason why I prefer wordy development notes than just a list of parameters it's useful for me to know whether it's what I want quicker than what I think I want based on name

Obviously you want detailed documentation too, and examples are great for quickly grasping bigger concepts and how to integrate into other systems. In my experience the best solution are both, where examples all have hyperlinks to the actual documentation for everything involved in the example. React is a good example in my opinion; there is detailed documentation of the api, overviews of the concepts, as well as examples that are included where necessary and as part of a walkthrough.

Even better are the challenges at the end of their examples which force you to rethink what you just read.

I agree that code is not documentation.

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.

The best docs are the ones that satisfy user needs. https://passo.uno/seven-action-model/

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

The Diátaxis framework [1] provides a nice suggestion of different types of documentation, and when to use them. None of these types is "best", each serves a different purpose.

[1] https://diataxis.fr/

You need both and there are no ways around that.

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.

tldr.sh is a project that had been doing this for man pages:

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.

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/

Examples are the best `quick start` documentation. Comprehensive manuals/references are the best documemtation.

when possible (python, golang and many others) I just go and read the source..

Radical opinion: If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, the method is probably trying to do too many things.

In particular, I don't want to have to learn half a dozen footguns because of a leaky abstraction.

Similarly, unix man pages desperately need examples. They are almost without fail written as an exhaustive reference for someone who already knows how to use the tool, which is a totally valid use case. But that means they're generally useless for someone trying to use a tool for the first time. Good documentation needs to have both.

Even better if the documentation examples are part of the test suite!

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

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

Totally agree but there is tldr for that.

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

This sort of thing really bugs me when I work with Unity and Unreal. Sometime the documentation for something is just so useless. A lot of the time when trying to understand Unreal nodes, the documentation page is just a picture of the node and the name of the node restated in slightly longer words, as if that helps anything. And so many times when I'm using Unity at £JOB, I just want to know how to use a function properly, and a short example would help so much. It's generally good but some pages just have nothing of value on them. If I could submit my own additions to the Unity docs pages, I would probably end up doing that

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

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

tldr was created specifically to address this miscoming of the manpages. And it's recent enough to not ship with any distros.

It's a false dichotomy good documentation should have both - comprehensive reference and examples.

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

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?

Checkout cheat.sh

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

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!

Carefully chosen examples are best documentation. Badly chosen examples are a mediocre documentation.

I've developed the habit of checking the end of the page, because that's where the examples are, when there are any.

> because you missed a config, or a preparation step

If the specific values of parameters of your mutable state are material to the outcome, then the example is incomplete if they are not specified. Similarly, you wouldn't use `fib(x) = 3` as an example without specifying `x = 4` in your context.

> don't understand how to process the results

Not sure when this would be the case. Do you have an example in mind?

In terms of actually documenting something, examples are not documentation at all -- they are merely illustration. The annotations accompanying the examples (if any) are better documentation than the examples themselves.

I'm not sure what you mean by

> Every project needs a varying ratio of each component and stacking all forms in a single website in the same format is very ineffective

I think Diátaxis _is_ mostly a conceptual framework. It helps me tremendously, totally implementation agnostic. From the site itself:

> Diátaxis strongly prescribes a structure, but whatever the state of your existing documentation - even if it’s a complete mess by any standards - it’s always possible to improve it, iteratively.

Like a lot of advice for documentation, it's not completely accurate. Good documentation should cover 3 "kinds" of users.

* Absolute beginners/newbies: These users are best helped by showing a "happy path" through the tools, with plenty of examples to show you why things are that way, so they build up an understanding of how things are supposed to work.

* Regular users: These are best helped by a "topic" oriented style of documentation. Topics can take one element of a tool and go really in-depth on it. For example, a HTTP request library might have a topic page entirely dedicated to session authentication, explaining how to persist headers and cookies between requests in the library and what a session object does.

* Power-users/developers: These users are served by reference docs the most. Just a big index of classes, functions and argument doc strings that refer to each other is enough here, because anyone reaching for reference docs is usually doing it because they have a very specific issue.

As for real world examples I'm familiar with; NodeJS libraries often only have beginner docs, and the moment you go off of that happy path it becomes very difficult to reason about what you're doing (not helped by a lot of frameworks preferring you use CLI tools to build up your code, maybe this has changed), the python ecosystem often has good topical docs at the cost of poor reference documentation and C libraries very often only ship with reference documentation.

Programming-wise, it's easy to make reference docs (since they can be derived from comments in the source code) and beginner docs (because you probably have a mental model on how someone is meant to start using something), while writing good topical documentation is an entire skill on its own (since it requires understanding where someone might struggle with something.)

The best documented tools usually have all three covered at the same time, while poorly documented tools usually only have beginner or reference documentation. Only having beginner docs makes it impossible for someone to really learn a tool ("draw the rest of the fucking owl"). Only having topical docs makes it hard to figure out where to start. Only having reference docs is hard to reason about because there's nothing explaining to you how the references are meant to fit together.

OCaml is really bad for this. Zero examples in its docs.

The best docs with examples I've seen are Qt (probably the best documentation overall), Rust and Go.

Examples are the best Documentation to learn.

If you are deeply knowledgeable about some library or language, examples become less valuable and the straight forward API documentation becomes essential.

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.

php.net was great for this back in the 2000s.

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

Real world isn't about calculating a fibonacci sequence.

Real world is usually a combination of

- read data

- trasform data

- obtain auth

- prepare data in proper formats

- <the only step usually shown in examples here>

- get results back. Perhaps an error? A stream? A specific format? Could we do retries?

That's why a full example would look like this: https://developer.auth0.com/resources/labs/actions/sync-stri... or https://github.com/stripe-samples and not a "it's enough to deduce parameters from method signature"

Say what you will about Perl, Perl docs are some of the most helpful. It's standard for docs to have a SYNOPSIS section up front that provides examples of common usage. This is followed by discussion, reference, and often more examples.

For example:

https://perldoc.perl.org/bigrat https://perldoc.perl.org/Archive::Tar

If you're writing docs for your project, consider following the Perl documentation style. Fortunately, that style is itself well documented:

https://perldoc.perl.org/perldocstyle#Description-and-synops...

While there is often a lack of examples in documentation, a lack of cogent conceptual explanations is unfortunately even more widespread.

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

I actually don't know, I just assume the majority of people are americans and that's why they use $. I don't use $ in programming except for string interpolation, so it's never really registered as a variable sigil to me

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

Oh no my PHPness is showing!

Also, many, many countries use $, like Canada.

> "it's enough to deduce parameters from method signature"

You don't quote me well. Here's what I actually wrote:

"If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, then..."

> <the only step usually shown in examples here>

Then those are poor examples. I'm not defending that poor examples beat out good technical specs, or even that bad examples beat out bad technical specs. Merely that, if a user-facing function is not misplaced at the architectural level, then good examples often make good technical specs redundant (for users) and provide strictly greater value (for users).

I'm aware of real world practices. I'm a real world programmer working with real world functional codebases, where parameters material to computations are always exposed explicitly, or at least their monadic context is. It is no pipe dream to highlight these parameters in full examples.

What often is a pipe dream is attempting to formalize and then update English language technical documentation. Ironically, one of the biggest offenders I might point to is the Rocq proof assistant. Their documentation has decent example coverage, but where it doesn't have coverage, and instead only has authoritative-sounding technical specs, it is abysmal. I have gone down rabbit holes to find out the real-world implications of typeclass resolution flags like this one (https://rocq-prover.org/doc/V8.19.0/refman/addendum/type-cla...), for example, only to find out that its behavior has changed from version to version without any update to its technical spec. This is because the spec, being mere English, was not specific enough to even distinguish between these different behaviors.

I wish it was a linter rule that people can't add type-hints until they've added at least one example.

Examples are also terrible as people will confuse them for the subject.

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.

> One popular community-based project in the Clojure world is clojuredocs.org, a site where people contribute examples for built in functions

When I was learning php in school, the examples / discussions on every documentation page were always the most helpful bit.

wait, isn't this a just-solved problem by asking your AI?

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

i have at times looked at tests to get an idea of how the developer expected the code to be used.

Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function.

Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I need to fix a problem or actually learn the library.

Also having examples is fine, but they should be considered a bonus; not documentation.

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.

I also had some issues recently where I was trying to build something in the latest Unreal version, and the docs for the thing I was trying to do said they were for that version, but obviously had screenshots from the last major version, which had a completely different interface style and menu items in different places, and as such was almost completely useless. Someone forgot to check it before bumping the version number on the docs

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.

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

Documentation comes in two halves, the examples and the reference, the examples are nice to understand how everything ties together, the reference explain how things work. If I only had one I would pick the reference. But having said that there have been times I would have killed for a simple example.

When I am learning something, I do tend to start with the examples, it is the best way to quickly get a feel for the shape of the domain and it's usage. But then end up in the reference in order to understand and apply what I just learned.

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.

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 use ImageMagick a lot and kept finding myself Googling for examples. I started writing notes for myself and recently combined them into a small field guide of command-line examples.

I go on to explain each of the arguments, however, which this blog post doesn't necessarily suggest. I think we need both examples and explanations.

My draft is still early, but it’s already useful for everyday tasks like resizing, optimizing, and layering.

https://news.ycombinator.com/item?id=45538609

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.

This holds true for product documentation as well. Too often docs are just a litany of detailed feature descriptions, which field and button does what, etc.

Feature-list type documentation is orders of magnitude less useful than workflow-type documentation. Majority of the time users are concerned with accomplishing tasks, which if the software is well designed, can be grouped, composed, and illustrated with examples. Key examples can be chosen to both showcase features and illustrate the main paths from "raw materials" to "finished workpiece", at various scopes.

This gap is too often filled by random youtube tutorials of varying quality. It's really telling of the massive blind spot afflicting the makers; they're too close to the details of what they build to see the whole, especially from the perspective of a user.

I am involved in a project that has little documentation and many examples. It sucks. A good spec or manual is all you need.

It's like googling "how to do XYZ with grep" instead of just typing "man grep" in the terminal.

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 don't use $ in programming except for string interpolation

... but the entire point of the "$JOB" etc. slang is that it's a string interpolation...

If you think it would reflect on you better, think of it as indicating regular POSIX shell use?!

(I'm 99% sure it's intended to be reminiscent of that sort of syntax. Example use: https://news.ycombinator.com/item?id=42761939)

Bullshit. Examples are the best excuse to not write documentation. I should be able to come up with an example by looking at the docs, not the other way around.

I just LOVE IT when i read a device datasheet, perform the steps and things don't work. Then i have to download a couple of GB or so of framework and configurator to generate a project that shows me all the details they forgot to put in the datasheet: order of operations, missing requirements, all that stuff.

Even better when the examples are not updated when the device / libraries / framework are updated

Documentation is like the system it supports too: the only unchanging ones are those nobody is using! I think this is obvious when we compare quality between the historically much slow manual releases with the cadence today, and the documentation of relatively slowly changing projects with newer, faster ones. It's a lot of work to create good documentation; it's even more work to keep it good.

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.

Every time I use $word in a comment is to be reminiscent of POSIX-style string interpolation for some word. The vast majority of cases where I've seen it are such, only if "word" is numeric do I expect $ is used as a currency symbol.

Not how I use it, string interpolation would be $"{job}"

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.

IMHO, not just an "example", but a dead-simple example. Just show me the absolute bare minimum of what I need to do to get this working, and I can take it from there. It really doesn't help me when you build a book store from the ground up when I am only trying to learn a specific part.

I'd go a bit further and say that all tests are documentation examples. Rust is nice because it has symmetry and documentation examples are tests.

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

The "Real" documentation is the implementation. Prioritize making the source code available and understandable.

Examples are very nice. One way to create examples is with test cases. Test cases can also be packaged with source code!

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.

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/

Documentation is often wrong, incomplete, poorly written.

If you only have N hours to work on "documentation", I say spend it on examples.

Also AI can probably turn a quality example into a doc whereas it can't turn a doc into a quality example.

Another thing to contemplate. I stand here as a 75 kilo entity - an example. I am, IHMO, a good example. The documentation on this example is so far many millions of page long, is very incomplete, certainly wrong, and could not be used to create said example.

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.

Very often before installing or using a library I want to look at functions and their parameters to understand how and if I can use it as I intend

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

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

> what you're asking for is type definitions

It's the API specification. It's not just the functions and their parameters, it's also an explanation of what they do.

> I'm much less interested in the specific arguments, and I'm very interested in "Capabilities"

And that's exactly what an API specification provides you, and that examples do not. Examples only tell you how to use the API on the same way that the author is using it.

The $ is for variables. And the upper case make it a BASIC variable, instead of something like Perl or PHP.

Some times people put it in angle brackets <JOB>. I have no idea what system use variables like that.

for years, i've been secretly wishing that doctests would take off because it seems to really solve two problems at once:

- it puts a simple usage example into the documentation - you get an easy-to-write, quick-to-run little assertion test that ensures basic functionality is saved

> You optimize for power users not amateurs.

Sure, but you can optimize for one without excluding the other. Adding examples _allows_ amateurs to gain experience and _become_ power user, and imposes near-zero cost on power users who can just skip a couple lines and get into the "real" API doc.

Sometimes, I just wanna remind myself how to use xargs for some command text replacement in a random one-liner on the terminal.

If I tried to do that with man... I'd have to read (in alphabetical order) the documentation for 6 different command flags. That's how far I'd go to read about the flag -- to actually use it, I'd have to experiment with the command flag until I figured out the actual syntax using my imagination.

Let's say instead that I am in a rush... so I'm skipping that time-consuming process and instead scrolling furhter down for some practical examples... one full page later I find a bunch! ... Except there's only 4 and none of them demonstrate what I need (the syntax is completely different). The docs wasted my time exactly when I most needed it NOT to do that. If I'd instead just googled "xargs replacement example", I would have gotten something I can copy/paste in seconds and could have gotten on with my life!

The moral of the story is this: Don't tell without showing. Don't show without telling. Do both if your goal is to be understood.

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.

The dlang website generator does not succeed unless all the coding examples run successfully.

PHP documentation stands out with the comment section, like an integrated stack overflow, with examples and gotchas. It's what made PHP great.

Types don’t explain intent or gotchas. They’re also useful, but you need both.

That depends on the language. In unix shell,

  echo $JOB

and

  echo ${JOB}

are identical, though the latter is more flexible (Allowing eg. `echo ${JOB:-unemployment}` or `echo ${JOB}SUCKS`).