We Are Hiring

API Documentation: Always Living With It, Can’t Live Without It


Posted on

Have you ever heard the one about the API with the perfect documentation? Yeah, me neither, and I wouldn’t believe it if I did. API documentation–all technical documentation, really–is notoriously difficult to produce, but just as essential to a developer’s life. If you’re reading this, the chances are you already know this to be true. And I’d place a bet that you’ve looked at some pretty bad documentation in an effort to make anything work.

This post shares four lessons to everyone who creates documentation. And, as one of these lessons shares, anyone who codes (and some who don’t) should play a role in some sort of documentation.

Start at the Beginning, If You Can

Chances are, at some point, you’ll be starting something that will need documentation. It may not be an entire product, but it may be a portion. If you can start at the beginning, do. If you’re way, way at the beginning of an API project, then you can prototype the API design. Like other prototypes (say, of an app or tool), an API prototype helps you see potential issues before they are baked into the API.

  • Quickly Prototype APIs with Apiary
    Elmer shares “API-driven development” through a sample to-do list API. Then he moves from a prototype, to a live API using Python and Flask.

One reason documentation can be bad is that sometimes it’s working extra hard to explain something that could have been solved by better API design in the first place.

Give It a Chance to Be Good

To create good documentation, you first have to understand what makes it good. As a developer, you know much of this internally, but it helps to spell it out.

  • Cheat Codes for Good Documentation
    Brandon outlines the importance of good documentation, which begins with understanding the goals of the docs. If you understand why you’re creating them, you can then make them better–Brandon writes about that in this post, as well.

If there were such a thing as perfect documentation, the above tips help identify how to get there. They can also help you get closer.

Welcome All Contributions

In the tech world, we give virtual high fives to companies that dogfood their own products. Really, this process should be expected, because that’s how you really feel like a user. Similarly, documentation is an excellent opportunity for dogfooding. Imagine if anyone consuming the docs could also contribute back?

The 85+ contributors so far to SendGrid’s documentation have made it better, and they’ve come from all around the world, both inside and outside of the company.

Remember It’s Always Changing

I started this post by saying documentation is never perfect. One reason, perhaps the biggest reason, is that documentation is always changing. Or, rather, documentation should always be changing, to match the world changing around it. To create good documentation, you need to lower the barrier to managing this change.

While Jekyll may not be the answer for everybody, the biggest takeaway should be finding a workflow that works.

As you consider your API documentation, start at the beginning if you can. If you can’t, don’t toss aside your hope. Since documentation is never perfect, all you can do is make it better. Look to others to contribute and make sure you have a way to get those contributions out easily.

Something more can always be done to improve documentation, so I’m sure I left something important out of this post. Let me know in the comments and then visit the SendGrid documentation and let us know how we’re doing.


Adam DuVander speaks fluent "developer" while serving as Developer Communications Director. He helps SendGrid connect to coders of all stripes. Previously Adam wrote for Wired, Webmonkey and edited ProgrammableWeb, the leading resource for APIs.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>