Hacker News Reader

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.

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.

View on HN

> Should we maintain "intuitive" end-user documentation separately?

The answer is a resounding “yes”. Definitions are an important part of API documentation, but user guides and tutorials are equally important if you really want to empower developers. OAS really doesn’t support much additional information outside of definitions and simple descriptions, so complimentary documentation is often needed.

I own server API SDKs at Mux, and we use OpenAPI to drive our generated ones. If you use OpenAPI and generate client SDKs from it (rather than expecting end consumers to do so -- there are usually enough rough edges in the base SDK that I find it worth doing so) it's pretty easy to pack these in by editing the README templates on a per-platform basis or the like.

Reply on news.ycombinator.com