API docs & anti-patterns: the good, the bad, and the ugly

Presenter: Alyss

api documentation, api best practices, swagger


Bad API documentation prevents people from using your API. And if users can’t understand your API, why bother writing one at all? I inherited four years of documentation, which meant facing a big ball of mud. It had been written and managed haphazardly by half a dozen technical writers and developers. Without search functionality, users relied on tribal knowledge and bookmarks to get to what they needed. In tackling this, I learned about the consequences of anti-patterns, why product owners are worth their weight in gold, and persona differences between API developers and API docs consumers. I will share my journey of untangling bad API documentation patterns and highlight strategies the audience can use to improve their documentation regardless of it’s starting state.

Takeaways from this talk include:

  • Strategies for improving legacy documentation via UX and information architecture
  • How API developers and doc consumers differ, and how to account for both
  • Overview of tools to benefit doc writers
  • How to detect common API documentation anti-patterns
  • Appreciation for the complexity of API documentation platforms and teams