Comment by horsawlarway
4 days ago
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.
> 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.
I really want both. I can follow examples and read specifications, but i likely want the simplest example first if I'm using a tool, and then the specifications after i've used it a few times.
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
Types don’t explain intent or gotchas. They’re also useful, but you need both.
The most annoying problem I run into with strongly typed languages or even typed python for that matter, is what on earth do I expect this to return?
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".
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