After nearly a decade writing API documentation for companies of all sizes, I have a handful of confessions to make.
Exported API reference documentation went out with disco. Okay, maybe that’s a stretch. But it’s spot-on when it comes to the struggles thousands of companies are suffering by using rubber-stamped API documentation.
Take Google for instance. They do so many things well and offer free services millions of users rely on to manage their lives. Their API documentation is written to hold the hands of users from developers to API newbies. They care. That’s why humans write their API docs rather than rely on automated documentation.
Stripe crushed it back in the day with their 3-column API documentation UI to destroy the long, long, long-scrolling antics of two column documentation. Recently, they’ve upgraded by using React modules for code examples. In my next life I want to be reincarnated as a Stripe developer.
Why are Stripe’s API documents 100,000 miles ahead of yours? They know the better they service users with crazy-easy documentation means more revenue.
They also own their docs. Duh, I know what you’re thinking. Everyone owns all of their docs you dumb tech writer. Keep reading…
What I mean is they own every shred of their UI output. They don’t rely on third-party tools to publish their documents in pre-formatted UIs. Instead, they build Ruby templates and then export .MD files to produce static API docs. Fast and furious baby, that’s how they roll. So should you.
Since we’re talking about UI gimmicks, please don’t do what one of my former clients did. They got suckered by someone in their organization to publish API docs in Drupal. Talk about a total disaster. Any time you start using a database CMS to manage your API docs, don’t forget that the Drupal CSS designed by marketing will be hard-wired into the API docs.
What you get are API docs that look like blog posts. In fact, if your marketing or UI department holds all of the decision-making power, be careful. Having working in marketing for years, I know they are doing their jobs best they know how.
But API docs need to be owned by either the technical writer team or devs (or both). Absolutely, marketing can pitch in outlining your style and brand guideline requirements.
My recommendation is using the Slate/Markdown 1-2 punch. Rob Lord has a free build on GitHub. You can use the template and then bust out the CSS and entire look to match your brand. I actually used Rob’s robust creation to build a project for docs.towerdata.com.
The way-back machine just called asking for your goofy help docs back. You know your API docs are dated. Your devs do too. Unfortunately, weak efforts to improve your documentation haven’t panned out right? Relax, I hear it all the time. But the answers to your documentation challenges begin with understanding your users.
A great way to start is to pinpoint all of your users and classify them into groups.
- Total pro developers
- Newbie API users too scared to ask questions
- Non-API users who could cut costs using your APIs
- Managers who have the budget but don’t understand tech
- Cross-functional users who see the value of your APIs but need help
Next, start researching their blockers. Gosh, everyone runs into blockers right? Reverse-engineer problems and then write help guides about them. Want to go one step further? Produce screencast videos and publish them in your help documents.
Then start pulling old support tickets to review the issues users are suffering through despite your well-intentioned documentation. If you API endpoints are banking big, fat revenue, start thinking about new features.
Your API documentation isn’t helping all of your users. Long-gone are the days when only brilliant developers are your users.
Solution-seekers are everywhere. Whether they’re trying to save a few bucks tapping into ShipEngine’s discount shipping API or the thousands of other consumer endpoints, guess what?
They need your help understanding the story of your endpoints. As in simple uses cases to help them learn about the benefits connecting to your APIs. Granted, smart developers can whiz through your reference docs and find what they need. Below is the short list of what I see being enormous opportunities for API providers to onboard new users:
- Do you understand your developer personas? They come with a variety of skill sets. However, the better you know your target users, the better you can create documentation to help them self-service problems regardless of their knowledge base.
- Are you writing documentation for each persona? This is a sensitive subject. Some companies see the opportunity to onboard all types of users rather than just developers. They understand lowering the bar of entry always equates to more API users.
- Have you outlined documentation templates for newbie developers? These are users who may understand the benefits of tapping into your APIs but need additional guidance. In a recent project I worked on, we actually targeted four different types of API developers in our documentation.
- Do you have an entry-level set of help documents to educator new users? This an area of API documentation gaining attention. Some of the companies I consult for are hot to pinpoint the best way to onboard total newbies.
- Can your marketing team get better at using your APIs? We all know that’s a silly question for some companies. Perhaps their marketing team couldn’t tell an API key from their car key. That’s cool. Get them involved making simple requests. Doing so will empower them to fine-tune their efforts to market your APIs.
API technical writers need to become testing fanatics. The good old days of hiring a traditional technical writer to buff up your docs is a great way to chase your users elsewhere.
Some dev teams consider onboarding documentation to their APIs as important as post-Halloween rotten pumpkins. Send users reference docs and call it good. Sure, ten years ago that worked perfectly. But now API solutions are catching the eyes of non-developers.
Well-intentioned developers rely on automated API documentation tools. You know, click, presto, chango, and voilà, your docs are exported for publication. I get it. Automated reference docs are simple to create. Cheap as snowballs in winter too.
Of the successful projects I’ve worked on, all of them were driven by the need to expand help documentation beyond reference material. It goes back to telling the story of your endpoints. You know, really getting down to the basic use cases and what the request body needs to pull off a super response.
My experience documenting APIs has been that if I can get my own API key and test the requests and responses, a funny thing happens. I become a real user.
When I can’t get an API key, a not-so-fun thing happens. I write about something that I can’t touch, use or break. Not ideal when you also need to document response errors.
Gosh, who hasn’t stared at the screen for hours wondering why in the hell the simple request won’t work? Syntax error? Bad object? Poorly provisioned API key? Who knows. I can’t test the sucker myself so I’m forced to wait for a developer to return my phone call so we can talk about the error.
What’s the answer? Testing. Then more testing. Hopefully lots of failures thrown in for copious doses of frustration. Technical writers need to be more accountable to the development side of their docs. For example, many of my technical writing friends stay clear of API documentation. Way too complex they tell me.
As a user, I want some help please. Pretty simple right? The challenge for many companies is they assume exported API reference docs help all users. Well, they do for developers. Are you ignoring other users?
On one of my last contracting tours, I had the pleasure of working for James Messinger at ShipEngine.com. He’s a proven disruptor of API documentation and has the expertise to boot. James is rebuilding their API documentation by offering all types of users the ability to learn, test and try out their shipping APIs.
In fact, James is taking their documentation to users who may not even understand the benefits of their discount shipping APIs. Remember, users have different needs. It’s obvious to ShipEngine and they’re building different types of API documentation based on the user.
For instance, it’s no longer acceptable for ShipEngine to rely on simple reference docs. Nope, now ShipEngine has a variety of help docs designed for different types of users. One set is for the pure API dude who simple wants the reference materials to ping their APIs.
Another set of help docs eases new users into the world of APIs by detailing why a user needs an API key and the benefits that go along with access.
Then another set of ShipEngine’s help docs provide real world use cases why each endpoint may benefit a user. Imagine that, a company committed to all of its users.
As a user, I want to be notified in minutes when your APIs are broken. This is a big deal and growing in the world of 24/7 365 API usage. Are you updating your API users in seconds when your servers are going wonky causing endpoints to fail?
Of the projects I’ve worked on in the last ten years, only three actually notify their API users when the sh*t hits the fan. They are:
- Stripe
- ShipEngine
All three notify users when their APIs are less than perfect. Google hardly sends updates because all of their stuff has been battle-tested.
Stripe actually sends emails with up-to-date information on why their endpoints are sucking fumes. ShipEngine sends emails the minute they detect problems.
Your developers are riding heard on bugs. Maybe they don’t have the ‘bandwidth’ to communicate massive outages to users. If so, too bad, you’re going to lose API customers.
Do you know key metrics of your APIs? Many companies don’t. Marketing and salespeople are ignored or worse, out of the loop when your endpoints are giving out bogus errors.
Onboarding and marketing folks are usually tasked with building adoption. Not explaining to their biggest clients why CPU outages are running rampant in your APIs.
So what types of metrics should your team be using? I would start by reading Derric Gilling’s suggestions. I’ve read his stuff for years and the kid simply gets it.
Why bother? For starters, there’s always more to the story about your users. Are they buyers or browser of your APIs?
What’s your new user TTFHW? Not sure what that is? Time to first hello world.
Are they delaying their first request because your API key documentation is blatantly wrong? They keep getting errors and think it’s on them. Hardly. It’s always your fault but if you’re ignoring brand new users, you are losing out on revenue.
New users are the lifeblood your growth. Go get ’em silly. Hug them, hold them, call them up and thank them for signing up for a free API key.
If your organization doesn’t understand brave customer service, go buy 100 copies of Hug Your Customers by Jack Mitchell. Make every single person on your team read it. Then have them write book reports about it. Demand buy-in and fire people who ignore the power of personalized service.
Back when I was working in broadcast radio and TV, I built a huge book of business by hugging my clients. Okay, not really, it would have likely gotten me beat up. But I cared about their business. Then I proved it by devoting myself to their growth.
What’s the first step? Pick up the telephone. Then call new users. Thank them for checking out your APIs. Offer them something free to keep them coming back. A 30 minute video phone conference with an onboarding specialist will easily get them hooked on your APIs.
Thou shalt market your APIs to your users. Are you? Do you do monthly video tutorials or Google Hangouts teaching your users about new features? Are you emailing API users a monthly newsletter? Doubtful.
Stripe is the granddaddy teacher of new features. They have their game-face on and dig teaching users about their super cool new stuff or how to use their existing APIs. Need proof? Cruise on over to their new site stripe.dev.
I know this may all be more of the same you’ve read about improving the user satisfaction. However, all of these suggestions are easy to implement if your team is devoted to growing exceptional user experiences.
