Never before in history have so many APIs been firing on all cylinders than now. The software industry is on a fast train to more jobs, projects and products.
I dusted off some of my favorite gems for this post. Ones I have borrowed and integrated into my projects. Albert Einstein summed it up perfectly…
How simple are your API docs? Don’t cringe thinking about it.
I’ve been speaking to many start-ups lately who are desperate to humanize their API user guides. Especially for new users.
Battery Daddy: King Kong of simple
Battery Daddy users don’t have to dig through junk draws to get their hands on fresh batteries. Simple stuff. Who’s junk draw(s) aren’t filled with batteries rolling around in the chaos?
Simple works. Even with API documents. The challenge for many companies right now is upgrading their docs. Often using outdated UIs and CMS platforms designed for blogging. Yikes.
Have you seen Battery Daddy’s commercials? One includes a person blindfolded on camera finding the batteries they need courtesy of the Battery Daddy. It’s slightly comical but also brilliant advertising.
Ok, it’s just batteries right? Hardly API docs. The simplicity of their advertising and design is exactly what users demand (and get).
How simple are your API docs?
Your API users are gold. They’re your customers, users, loyal fans and revenue sources.
- Do your docs help users self-service their needs?
- Are you stuck with service tickets from blocked users?
- Are you calling customers to find out if they need help?
I get it. API docs are for developers. I agree if it was 2015. These days API users come in all flavors. Huh, really? Yes. They’re not only developers anymore.
Who uses API docs besides developers?
Back in 2018 I had the pleasure of rewriting all of the ShipEngine.com API docs. Well, after testing every single one of their endpoints with Curl. Some of their users have never pinged a single API. So I wrote this introduction to REST for their newbie users. Heck no, seasoned developers won’t read it. But brand new users will since they’re brand new.
API docs gem #1: testing
Testing endpoints is required in my book when writing API docs. I’m referring to the process of acting as a new developer onboarding myself to your API platform.
Self-service is critical. Even when their responses contain errors. Automated API testing is super. Human API testing is super duper.
Rock-solid API technical writers are all in on testing endpoints. Do all of them test? Nope. Hardly many.
Let’s define testing…
Get an API key and fire up Postman or Terminal or your preferred tool. Then start making requests. That’s it.
Testing requires commitment and industrial-strength honesty to ask for help when the dreaded errors are returned in your responses.
Collaborating with developers to find out why the error happened is job #1. Often it’s a syntax error or worse: incorrect parameter values.
API docs gem #2: publishing
How are your API docs published? Are they public? Or private?I’ve worked on both public and private API help doc projects.
- If your API docs are public, how quickly can you update existing documentation?
- Hopefully your answer is hours and not days or weeks. If it’s months, you have a massive manpower problem.
Agile publishing is what all thriving API providers strive to achieve. Ones who do retain customers and users for years.
Private API docs are common. Especially in the payments industry. I’ve had the fortune of working on a handful of FinTech API projects. Often they share their API docs via PDFs.
For example, one global payments processor I consulted relies on PDF sharing to control access to their API help docs. When you process $29 billion in virtual credit card payments a year, controlling access to onboarding documentation is wise.
Not all companies or dev teams can publish API help docs quickly. Forward-thinking scrum teams and product owners understand their API users are like gold to their company’s revenue source.
- Every enterprise payment provider I’ve worked with have their own methods backed by risk profiles.
- Less access to sensitive API docs means less risk of thieves and hackers getting their paws on proprietary information.
Publishing public API docs is easy What’s interesting is many companies are stuck in the stone age. They’re using lame or outdated CMS platforms to publish their API docs. Ouch.
A few of my recent finds in the A+ API docs department…
Some of the above sites are static. Please think about using a static site generator for your API docs. Try avoiding database sites like Drupal or WordPress to publish your docs. They’re far too slow.
Here’s a static API doc site I built in 2018 for TowerData: docs.towerdata.com. The need for speed is required for API documentation publishing.
Sad story…
One former client of mine built their API docs UI with Prismic. It’s a blogging software. Clearly someone unqualified made the Prismic decision. Unfortunately, they didn’t understand API docs require lots of tables in every document.
No tables to define parameters and miles of other information is borderline insane. Tables are a must (duh). Check out a ShipEngine table…
- Notice in the ShipEngine table I added links.
- The links navigate to other pages of long-form introductory help guides designed for users in need of a buff up their knowledge.
Helping users in seconds find relevant content to self-service their blockers is the granddaddy goal. So linking out to related content serves users in a proactive style helps solve user problems.
API docs gem #3: analytics & monetization
My background is rooted in sales. Then customer service. So I love getting access to API usage analytics.
- Knowing exactly your top 10 API endpoints used by your customers is a beautiful thing.
- Especially if you’re looking for ways to monetize existing endpoints and build new ones based on user data.
Are your sales teams and onboarding specialists meeting with product owners regularly? Discussing API usage and new product enhancements usually results in happier API users and customers.
I’m talking about a collaboration between sales and API product owners. Granted, enterprise orgs may not have the bandwidth to support these types of meetings. Ones who make the time to grow their API brand are far more likely to overtake their competitors.
One of the API analytics solutions I’ve used is moesif.com. It’s a powerhouse helping you pinpoint new users, how long it took users to onboard as well as your API user retention rates.
Curious what I’ve done in the last decade or more? View my portfolio. If you you have a new project in need of a passionate technical writer, send me a note.