Developers April 22, 2020

Are runnable code examples in API docs good DX?

Patrik Krupar @pkrupar

I just finished up making a few improvements to sidemail.io docs, and one of the things I added are runnable code examples (Runkit). I borrowed the idea from Stripe, which does the same thing on their landing page. But, I've never seen it used in docs before, and that makes me wonder if it's good DX.

Here's how the runnable code example look.

As a developer, would you find it useful when integrating 3rd party API?

PS: runnable examples are only visible on screens wider than 800px, sorry mobile users!

  1. 2

    As someone who has been looking for certain Api providers I can tell you that its super beneficial to have runnable examples on your docs. It makes it super explicit to know what you'll be dealing with. If not a runnbale example then atleast a whole url

    1. 1

      Makes sense, thanks for the input!

  2. 1

    Personally I wouldn't find it useful because you can see what the code will do, I wouldn't find the need to actually run it. If it isn't obvious what the code will do by reading it then maybe that's a bigger issue.

    I also never bother running stuff on CodePen though so I might just be an outlier

    1. 1

      "If it isn't obvious what the code will do by reading it then maybe that's a bigger issue."

      that I totally agree with. Thanks for the input!

Recommended Posts