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?
- Why We Open Sourced Our Documentation
In September, SendGrid open sourced our documentation. If good documentation encourages feedback, then a GitHub repo is about as open a method for feedback as it gets for developers.
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.
- Create Sustainable Documentation with Jekyll
Brandon chronicles the documentation platforms SendGrid used through the years and how he landed on Jekyll as a lightweight way to make documentation sustainable.
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.