New features!
Help Center
Developer Resources
LoG IN

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

Accept

Sign up for education resources for teams who want to increase customer acquisition and retention rate

Blog

Documenting the API with readme.io

by 
 
Sep 17, 2019

How to create better API documentation, references, write specifications - Voucherify's personal experience with readme.io infrastructure.

Documenting the 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 THE PERFECT

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

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.

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 customer acquisition & retention tactics with incentive-based platform

Start free trial

{{ENDCTA}}

Personalized promo campaigns convert

Sign up for education resources for teams who want to increase customer acquisition and retention rate

By registering, you confirm you have read and agree to the Subscription Agreement, and to the storing and processing of your personal data by Voucherify as described in the Privacy Policy.

Marketing Permissions

Before you send us your data, you must become acquainted with the Privacy Policy where you will find information on the personal data controller, your rights and our obligations, the purpose for which your data are processed and any other information which relates to the protection and security of your personal data.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.