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.
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.
it's much harder to imagine everything a tool can do with only the specs, and I'm not clear what things I'm missing. Examples make it concrete
With python, it could be a mysterious class that isn't explicitly mentioned.
For Rust, you often need to know 4 layers deep of nested types for various error and flow control, and once generics are introduced with the expectation of implemented traits, it all goes out the window.
If I need to declare the type of a value ahead of time, or know it's shape to serialize, check, etc, I want a very clear "this is what it returns, this is how it's expected to be used".
Good documentation is hard, and very rare these days.
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.
The best documentation is type references and examples and a line explaining what the function does. Not one or the other.
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.
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.
"No true Scotsman would want examples."
I'm far from an amateur and I want to see several concise examples in documentation. That doesn't mean that's all I want to see.
They're not the best. The best is thorough api docs. The rest is nice to have.
And I'm not no true scotsmaning, I'm just saying most devs are ass. I know, I see people with 20 years of experience on me write buggy trash code that I have to fix. I see people whine about the java docs as if they aren't some of the best damn docs available anywhere. Because they're ass and they can't properly use the tools they're given. They'd rather have examples and copy snippets from SO or have ChatGPT write it for them.
Any professional will appreciate proper documentation. It is literally impossible to create examples for every situation. Api docs, by their nature, cover all use cases because they simply describe what exists not how to use it. So for those of us with the knowledge and intelligence to actually just look at the parts and put them together on our own, ie professionals, API docs are king. Examples are useful sometime, API docs are useful all the time.
But of course if you don't even know the language well enough to read the documentation, you prefer examples.
That's exactly what you said.
And I'm not no true scotsmaning
You absolutely were. Now you're trying to backpedal.
If you don't even know the language well enough to read docs I'd say you're an amateur. And if you're one of those people who just chronically don't read docs you're definitely an amateur. I mean you may have a job and you may even build stuff that kind of works, but unless you're sitting down and looking closely at the details you're not doing things right. You can't be. Doing things right requires looking closely at the details.
And I know from experience that there's a vast number of employed amateurs who write nothing but legacy code.
I don't understand the resistance to examples being a part of documentation (and not a bonus).
I think harimau777 was just expressing his opinion, like the blog owner.
E.g. "Python rstrip" (without quotes) in DuckDuckGo does not lead me to the Python docs on page 1.
Now, languages with common / short names? All the time. Go, C, C++, D, etc; even Rust (especially since all the libraries have similarly ambiguous names related to iron oxide).
Am I uncommon in that I search for the website/domain I intend to read first and then look for the specific page?
I think so!
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.
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.
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.
I'm not sure it's inefficient. It gives you the knowledge what is and isn't possible and also the semantics of what you actually do, all things you need to have later anyway. Relying only on examples is a great way to miss unintended side-effects or other consequences.
This way the examples must always be valid and runnable.
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.