Documenting API With readme.io

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.

Chasing perfection

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.

Everyday readme.io

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 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 manoeuvre between articles.

The Customer Context

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.

GVFM Family

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!

{{CTA}}

Learn how to improve your retention tactics with incentive-based platform

Start free trial

{{ENDCTA}}