If you’re a hiring manager or product owner, you’ll likely be able to answer this question without extreme brain power…

What comes first: the API code documentation or your end-users?

Pretty easy right? Wrong.

I’ve seen many API interfaces which look like the scattered remnants of a 23 car highway pileup. Granted, there’s no blood and guts. But your end-users are surely traumatized struggling to pour through your documentation.

Answer? End-users (duh).

#3. Someone thinks 1993 innovation still works.

In 1993 Adobe launched portable document files. For some reason, many API documentation decision-makers have a mad, passionate love affair relying on PDF documentation.


Obviously, technical writing teams spend their days in MS Word and perhaps inside a CMS. But nowhere is it written anywhere, ‘Thou shalt document API user guides in hardened concrete.’

Never, and I must repeat, NEVER output your API documentation in PDF format.

But why?

Ease of accessibility. Not long ago I consulted with a banking client which crafted a 134 page PDF of their API documentation. Huh?

First of all, most programmers aren’t going to leaf through it to find what they need. Even on screen, they’ll be stuck scrolling up and down or doing searches.

The long-form approach to API documentation contained in one mighty tall document is officially older than dirt.

What’s the exception? Financial onboarding documents. These are sensitive pieces of content not intended for publishing publicly. So in some cases, PDFs do offer internal controls for security.

Next, if you’re API documentation isn’t hardwired into a dynamic interface (read more on this below) your users will groan. They’ll waste precious time in between toxic rants how your documentation is destined for disaster.

There’s nothing worse than closing a massive new sale and discovering they suddenly hate you, your product and everything you represent for one reason:

Their developers think your API integration documents are pathetic.

#2. Your find-factor needs a facelift.

Demanding that end-user developers paw through endless pages is a blithering nightmare. You need to start thinking more about end-users and making access to your API documentation fast and easy.

I’m referring to the need for a dynamic, one page UI. Not 48 pages linking back and forth.

Think one. As in one interface where every shred of your API documentation exists.

  • Can they find which code examples they need in seconds?
  • Do you provide multi-color code examples to make distinctions simple?
  • Are your programming language code examples displayed with¬†tabs?
  • Does your documentation¬†include syntax highlights?

Developer tools are brilliantly designed to illuminate lines of code with color controls. A project I collaborated on recently involved building a three-column one-page UI with programming language binding tab functionality. It’s the granddaddy design that successful companies are using to document their API resources.

Eye strain is the big issue.

Color is critical making end point distinctions clear. The worst thing you can offer end-users is a dull, all black text set which is difficult to view and decipher.

Tabs are now the gold standard presenting diverse programming language documentation.

Improving visual contrast of your sample code provides users quick scanning ability rather than forcing them to slog though reams of one-color content.

#1. Your developers love auto-generated documentation.

I know, the quick and easy method is to use an API tool to generate your documentation.

Sure, Postman and Swagger are one-click solutions and all the rage these days.

The problem is your technical writers aren’t developers. How can they pinpoint what’s what and create the user-friendly content?

They can’t.

Below is a sample of an auto-generated output:

What’s missing? 6th grade-level clarification.

Too many times developers make assumptions. Ones such as end-user developers should be able to comprehend integration based on thinly-sliced documentation.

But the information gap gets worse.

Suddenly the customer needs help. The salespeople or relationship managers have no clue.

If you’re lucky, you may be able to harness the attention from one of your API developers to help. Next comes language barriers if phone calls enter into the mix.

How can you engineer your documentation to be brutally clear? By writing it for the lowest common denominator developer skill set.

Stripe and Paypal do it flawlessly Obviously, the last thing they want are integration nightmares. They have services to sell as do you.

Building a dynamic three-column API documentation UI with code examples cuts through the clutter of confusion and assumptions.

This isn’t rocket science. Honestly, the gaps I see in many companies is the lack of accountability to communicate flawlessly for the end-users. Granted, much of suffering is caused by weak technical writers who don’t get phenomenally good at learning API integration writing.

Learn more about my expertise cutting through the clutter of API documentation.