This looks great, but many orgs use auto-generated documentations for client libraries (e.g. OpenAPI), which IMO doesn't give you easy-to-understand introduction/overview. And I've seen many documentation I have to decipher.<p>Although tools like OpenAPI has its own place when it comes to documentation, should we maintain "intuitive" end-user documentation separately? I don't think this can be automated based on the code.
> what your API does and does not do<p>This could mean specifying a LOT of things that an API cannot do, but it's easier to state what an API can't do rather than list all its capabilities, similar to how people can list 100s of negative emotions and fail bad at specifying lots of positive emotions.