UK Government Guidelines on Documenting APIs

gov.uk

55 points·pcr910303··5 comments

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.

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.

> 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.

> what your API does and does not do

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.

I don't think they expect you create an exhaustive list of things the API doesn't do. I think instead that if there's missing functionality from what you could call a 'complete' API, it's useful to call that out. E.g this API is for processing images, but we don't support PNG

Reply on news.ycombinator.com