Most APIs rely on reference documentation (Open API spec/Swagger, RAML, API Blueprint) to explain what they can be used for. We believe that’s a mistake. When building devportals for our customers, we started recommending the use of a short introduction for each API. In it we try to explain its most important functions, making it much easier for both developers and decisions makers to learn what its benefits and features are. This not only makes it easier to decide what API to use, it also creates a better developer experience when implementing an API. So far we’ve called this documentation type the API description, but I realised this is confusing and I’m looking for a new name. Want to learn more, and maybe even help me find a better name? Don’t miss this talk!

In this presentation, I would like to share what I’ve learnt so far, and show how to use templates to create API descriptions and how to apply them on internal developer portals.