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

Get inspiration to grow

Stay up to date with the latest marketing, sales and services 
tips and news from Voucherify.

Get inspiration to grow

arrow pointing left
go to blog
Technology

Documenting API with readme.io

Mike Sędzielewski
Mike Sędzielewski
September 27, 2017
Share it on Twitter
Share it on Facebook
Share it on LinkedIn
Share it on Twitter
Share it on Facebook
Share it on LinkedIn

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.

API and readme.io

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 like this – https://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 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}}

Share it on Twitter
Share it on Facebook
Share it on LinkedIn
Mike Sędzielewski
Co-founder of Voucherify and rspective. Fan of API-solutions for marketing automation and headless approach in digital marketing and sales. In private, he enjoys reportage and everything non-fiction.
More articles by this author

Join our newsletter

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.
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 for subscribing to our newsletter!
Something went wrong while submitting the form.
Close

Are you wasting time and money on digital promotions?

It’s time for a change.