[chickenzzzzu]

Entirely 100% true. I can count on one hand the times I've said "wow, this documentation was written by someone who cared". Threejs is a good example here, but even then it is subject to API rot and needless reference chasing.

Examples are often the best way to do documentation, sadly.

[all2]

I've been leaning on test suites more and more for this. It's almost like a test suite should contain comprehensive tutorials. You know the API is good (hopefully) because if it isn't, the CI/CD pipeline wouldn't have let the release through.