Maybe don't even worry about documenting the "height" parameter. I'll figure out if it's in pixels or percent or rems soon enough.
But if you have a parameter called "snefbolian" I really want a paragraph or more explaining that, it isn't sufficient to give the unit.
- Poppler
(Yes, I know it's because they're using printer vocabulary for rendering. I know this because I googled the magic numbers in their example code. It would have been nice to read something on the docs)
I remember the original react docs were great for teaching the vocabulary, but then it seemed we had to figure out sentences and paragraphs on our own. To be fair, I started that journey during (or soon after?) the beta. It would be unreasonable to expect more from the docs at that point.
But we definitely need an intermediate and advanced level of documentation for these things:
> Now that you know how to use vars, loop, etc, let's build a [app] from scratch to see how it all works together.
And then...
> Now that you understand how to build [app] from scratch, let's use some advanced techniques to improve the app. Here's why we do this, that, and a third as our app grows.
And it needs to be something more significant than a TODO app. I get the appeal of a TODO app. It's basically the simplest useful form of CRUD. But that simplicity is why it's not the best example beyond introduction.
You can read the docs about given library function but often it's not clear how that certain function should be used in practice, leading to confusion and ultimately Stack Overflow.
But even reading code for projects like a todo app will show you how the code can be put together but necessarily higher level understanding.
In other words, the kind of eurekas you think people should be able to glean from a real world example are great to establish in plain text. For example, imagine what you would write if you had a blog post that walks the user through how to build the todomvc.
Another example is how I launched two macOS apps to the app store before I realized that the Combine api was supposed to be used and abused rather than a lower level api to be avoided in favor of other state management levers. And all it took was for someone with much more experience to simply tell me.
I think it’s the hardest part of writing docs. And maybe you do it somewhere, I only read the api reference pages.
The best example of this I can think of is mhartl’s Ruby in Rails tutorial. It has lots of wisdom about the “why” instead of just the “how”.
SwiftUI is a great example of this struggle where the docs show API building blocks but tend to end before getting across the sort of higher level understanding that lets you synthesize less-trivial patterns on your own.
The Combine docs (SwiftUI’s reactive/observable abstraction) will go on and on but never explain that this is the tool you are supposed to use for, say, computed properties, so most people will try to create more @State constructs that get updated in a didUpdate block or come up with some other solution.
It’s something that’s easy to take for granted when using React where the docs try to give you at least a raging clue about intended use cases and are considered failures if they don’t, and it’s popularity means at least many have asked the same questions before you.
It’s a major point we dismiss when we complain about people “cargo culting” popular tech, especially in the UI space where the Best Solution remains an open question and the subject of continual experimentation.