We use cookies to help us improve, promote, and protect our services. By continuing to use the site, you agree to our cookie policy.

September 27, 2017

Documenting the API with readme.io

Mike Sędzielewski
« Go back

In this post, we share some insights about the process of creating better documentation at Voucherify and the role of readme.io along the way.

A good specification is a clear number one when it comes to business-to-developer marketing. Often, it’s their first and most frequently used touchpoint when they investigate a particular tool. All the more reason for any API-first software company to get it right from the outset.


Recently, we decided to take our docs page to the next level. We started off by looking for a role model; we asked a dozen senior coders who work with API/SaaS products on a daily basis: What’s the best spec you’ve ever seen? The winner emerged pretty quickly - Stripe. We especially liked how they keep the general knowledge base and the API reference in a clean and separate manner. We wanted to follow this pattern.

At the time, we had been using readme.io in the ‘developer hub’ plan. We soon realized that we’d have to upgrade the plan to achieve the new design, but that would be a pity, because it was way more expensive. So, after some digging, we found this button:

We gave it a try and bam! We ended up with a new, almost-Stripe-like layout. One site for tutorial and examples and a one-pager perfectly suitable for coupon API reference. Plus, a nice panel to navigate between them.

The migration was fairly easy, however, whereas the endpoints’ descriptions had been automatically migrated, the links pointing to them had not. Sadly, we had to fix them manually, nevertheless, the overall outcome was more than satisfying.


With the new API reference site, we love readme even more. This is a spot-on addition to the already great infrastructure which supports us in the developer onboarding process.

We won’t describe every single feature of readme, but let me say that with the WYSWIG editor, templates, syntax highlighting, code examples, confluence-like link autocomplete, and emojis, you can roll-out a quickstart site like thishttp://docs.voucherify.io/docs/getting-started in no time at all. You can also quickly put together a profound endpoint’s description enhance with examples e.g. https://docs.voucherify.io/reference#redeem-voucher. But, you should probably try it yourself to get the real picture.Apart from the intuitive edit mode, we have to admit that the navigation is slick as well. On top of that, a decent search makes it easier to maneuver between articles.


Finally, for a tech-oriented product like ours, having an insight into user activity on the documentation page can be super valuable. Readme takes care of that too; although they don’t provide in-app tracking features, they let you integrate Google Analytics, Segment, and Heap analytics.

Likewise, we found the Intercom integration useful too. We can answer developers’ questions right from a tutorial page. And Intercom shows us which page they’re looking at, so we know the context immediately.

There is one thing we miss, though; we’re getting more and more questions regarding the product and some of them are repeated every now and then. We’d like to create a fast FAQ which can intelligently suggest a respective article. We wouldn’t complain if it offered a customer tracking capability too. While we know they have it on the roadmap, Intercom has just released a serious alternative.


Readme (next to Postman) is another good value-for-money tool we happily use at Voucherify. And we’re sure we’ll leverage even more of its features when our coupon API grows, e.g. versioning at the very least. We’re also excited to see new releases from Gregory and his small-but-super-productive team!

marketing tools
« Go back
Related posts