Hm. I'm trying to see how these examples here match what the article focus is.
The article focus is the shape and structure of useful documentation, provided by the project or by third parties, that, the article doesn't say.
Now. Skillets are a commodity. Training material is completely detached from the product, except maybe for cleaning and maintenance. For motor vehicles, driving instruction is detached from the product. The vehicle manual focuses on how to use _this_ car (in contrast to how to use _a_ car, e.g. in traffic). And violin expertise needs a personal trainer.
And likewise, for some programming languages, for example a C compiler, the user manual just teaches how to configure _this_ compiler. It won't teach you C. You buy separate books for C.
But for a new language? a new paradigm?
Let's look at an apples to apples comparison, what would be real-world products of comparable complexity? Advanced Games could be an example. Physical Games that is, like Settlers of Catan.
And of course these come with documentation, because of course they'll desperately fail if the documentation isn't helpful.
We could argue if the presentation of how to get to useful documentation fits today's attention span, I think both the article and the linked resources are very chatty, but the contents is worth reading if you want your technical software product to be successful, imnsho.
The article felt off to me, and trying to pinpoint why led me back to the core premise of it.
On the examples given, we're talking about building tools. The point of a new library is to integrate into projects, understand its model, adjust and maintain it (deal with the requirements, dependencies, upgrade cycle etc), so to me getting taught how to use it is only a small part of the story, and could be potentially irrelevant.
I've used brand new libraries that have absolutely no documentation and it was fine for me and the team.
What the article really focuses on is perhaps more akin to quick onboarding and marketing.
> what would be real-world products of comparable complexity?
A new car will be the same level of complexity. You see it as different if you focus on the simplest part of it (going from A to B), but even for driving a new car will effectively have a learning curve, he tires don't grip the same, the engine requires a different driving style, the length and volume might require adjustement as well. And that's only the tip of the iceberg, as you'll need to understand how it's wired, how the panels are assembled and what standards are used for the parts to maintain or adjust it to your needs. You'll need to dig deeper if you're planning on running it on tracks or races.
Settlers of Catan comes with a booklet because the rules are the game, and the whole point is to bind the players to the rules. That's generally not the case for building tools (except for DRM or license management?), surely not for a new language.
The article focus is the shape and structure of useful documentation, provided by the project or by third parties, that, the article doesn't say.
Now. Skillets are a commodity. Training material is completely detached from the product, except maybe for cleaning and maintenance. For motor vehicles, driving instruction is detached from the product. The vehicle manual focuses on how to use _this_ car (in contrast to how to use _a_ car, e.g. in traffic). And violin expertise needs a personal trainer.
And likewise, for some programming languages, for example a C compiler, the user manual just teaches how to configure _this_ compiler. It won't teach you C. You buy separate books for C.
But for a new language? a new paradigm?
Let's look at an apples to apples comparison, what would be real-world products of comparable complexity? Advanced Games could be an example. Physical Games that is, like Settlers of Catan.
And of course these come with documentation, because of course they'll desperately fail if the documentation isn't helpful.
We could argue if the presentation of how to get to useful documentation fits today's attention span, I think both the article and the linked resources are very chatty, but the contents is worth reading if you want your technical software product to be successful, imnsho.