This talk was given at RailsConf 2018. For a pared-down text version of the talk, see this post. For the real thing, here’s the video:

And the slides:

P.S. If you happen to subscribe to RubyTapas, you can also check out a brief, more technical take on the same material in my guest episode!

Talk Description:

Ugh, documentation.

It’s the afterthought of every system, scrambled together in the final days before launch, updated sparingly, generally out of date.

What if we could programmatically verify that our API documentation was accurate? What if this helped us build more intuitive APIs by putting our users first? What if documentation came first, and helped us write our code?

With Swagger and Apivore as our weapons of choice, we’ll write documentation that will make your APIs better, your clients more satisfied, and you happier.