Minimum Viable Documentation for RESTful APIs
Mike currently works for GitLab, with documentation responsibilities for the Manage stage of products. Mike has documented new features for ForgeRock Identity Management and Access Management products. Mike has worked in on-premises and SaaS environments.
Mike has also written a couple of dozen technical books, mostly focused on Linux certification, and is the author of O’Reilly’s Linux Annoyances for Geeks.
To paraphrase a James Bond movie, “Swagger is not enough”. You’ve done the work to set up REST calls for your APIs (Inaccurately known as Swagger). You have reference information. But you discover that few users are actually trying REST calls on your system. You’re wondering: “What else do I need?”
This presentation will describe the Minimal Viable Documentation (MVD) for RESTful APIs, also known as “What do I need for my developer portal?”
Based loosely on Kristof Van Tomme’s presentations on Developer Experience, Mike will describe the MVD for a developer portal, which will help your developers try out your APIs. He will discuss the characteristics of:
- Landing Pages that describe the API
- Tutorials that help the user get started
- Details, or reference information satisfied by the OpenAPI specification
- Work in Progress such as blogs and release notes that show active development
While Mike gave an earlier version of this talk at the API Strategy Conference in 2018, he’ll update this talk for the latest API portals.