The subject of API documentation reveals a fascinating property of the software development industry that makes it truly unique.? When you think of a product, you think of something polished and ready to ship.? That’s true of software and also of the broader world in general.? But only in software can you crack the product open to reveal its internals and then ship that as well, with a different purpose.
When you expose an API, this is exactly what you do.? Take an offering like, say, the iconic Trello.? On the surface, you have a lightweight kanban utility with a nice user experience.? But you also have an underlying platform for developers to use.? Through the Trello API, developers can build their own functionality to extend and enhance the offering, creating a win for everyone.? Developers win because they can do cool things.? Trello wins because it generates more interest in their offering.? End users win because they have a richer set of functionality at their disposal.
Of course, extensible software is hardly new.? But these days, it’s becoming more and more the norm.? And it’s also something that companies plan for from the get-go, rather than scrambling to bolt on at a later date.? So it’s important to treat APIs as first-class citizens, conceiving of them as actual products and doing things like, say, shipping API documentation.
What is API Documentation?
Most people reading can probably infer what this means, but it’s worth being explicit before proceeding.? API documentation is a standalone set of deliverables that you offer to clients of an API.? And for the sake of thoroughness, “API” stands for “application programmer interface.”? So you’re documenting how programmers should interact with your platform through code.
At a bare minimum, your API documentation should include information about setting up to use the API.? It should also describe the different function calls, parameters, and return values.? Sophisticated API documentation will also include examples, caveats, gotchas, and any other useful tidbits that might make life easier for developers.
Is API Documentation Really Necessary?
Could you ship your product and API with no documentation?? Sure.? Could this work out for you?? Probably, somewhere, somehow.? But I wouldn’t call it a good idea in most cases.
The entire point of an API is to open up your product for extension.? You invite developers to come in, poke around, and get comfortable.? You want them to use your product, extend it, and build a community around it.
Without API documentation, you’re not really rolling out the welcome mat.? Instead, you’re leaving it up to them to learn by trial and error what to do.? The probable result?? They’ll try, get frustrated, and leave.? Or perhaps they won’t try at all, viewing it as a waste of time.? Either way, they’ll go looking for your competitors who, presumably, have nice API documentation.
So let’s assume that, all things being equal, API documentation is desirable.? What are some strategies that shops have for their API documentation?
API Documentation Via Oral Tradition
While not doing any documentation is technically a strategy of sorts, I won’t cover it here.? Instead, I’ll talk about what, with tongue planted in cheek, I’m calling “oral tradition.”? This looks similar to the “we don’t bother” strategy of documentation in that it doesn’t produce documentation artifacts. But there is a strategic difference.
What I’m driving at here is a decision to support API users via a form of hand-holding.? You’re not publishing documentation that you ship alongside the API, but you do make the effort.? Instead of giving them docs, you actually talk them through it or, potentially, work on it with them.? You might supplement this with ad-hoc communication, such as emailing them an example.
If you work on a product like Trello, this sounds insane.? But consider that not all APIs have equal constituencies.? Perhaps you don’t generally support an API at all, but you’ve opened up some of your code to a major B2B client for integration.? In this case, it’s so custom and specific that creating documentation makes no sense.
Using MS Word or Something Similar
Let’s move past the case of highly specific APIs for custom partners and into the realm of broader, more general consumption.? When you throw your API open to the public or to any arbitrary paying customer, you need something tangible.
One tried-and-true way of doing this is to write user manuals in some form or another.? This has roots going all the way back to man pages, and probably beyond that.? Whatever the particulars, you put your API documentation into some digitally or physically distributable format.? MS Word is a common choice, given its ubiquity and formatting capabilities.
But whatever you choose, the mechanics are the same.? A developer or technical writer goes through the API and, well, writes about it.? This generally includes everything I mentioned under “what is API documentation” and probably more.? After all, it tends to have the feel of writing a book, naturally lending itself to verbosity.
This is a well-worn path to pleasing your users, and it has a lot of merits.? The main downside, however, is that it’s extremely labor intensive.
Automated Documentation From the Outside In
Since historical methods for generating API documentation proved so labor intensive, it should come as no surprise that people used automation to relieve this pain.? While you certainly can fire up MS Word and write all about your API, you no longer need to start from scratch like that.? Tooling has caught up.
The first tooling approach that I’ll mention, I think of as outside-in API documentation.? You build your API as you normally would, exposing the functions and means of interaction.? Then you point a tool at your API’s surface.? The tool parses it exhaustively and generates initial documentation based on its findings.? From there, you mark it up as you see fit.
Swagger offers an example of this.? You build a REST endpoint that you expose.? Swagger takes that contract as input and generates your initial API documentation from there.
Automated Documentation From the Inside Out
Now let’s consider a complementary approach.? If you think of outside-in API documentation as black box, we’re now talking about its white box counterpart.
Here’s how this works in concept.? Given the source code for an application with an API, you use that source code to produce the API documentation.? This happens by inferring various properties of the API — member visibility, parameter and return types, exceptions generated, application behavior, and even code comments.
In fact, code comments can be an excellent means for this style of API documentation.? GhostDoc works this way.? Assuming that developers tend to create well-formed method header comments anyway, it uses those as the basis for generating help documentation.? You thus kill two birds with one stone: commenting the code for maintenance purposes while generating documentation for API consumers.? Developers never need to open MS Word (or whatever).
What Strategies Do You Have?
My intent here was to broadly cover some options and to offer heuristic advice.? Having done the former, let me do the latter.? Whatever you choose, you should automate it as much as you possibly can.? This helps you cut down on your labor and save time and money.? You should also pick something idiomatic to the techs you’re working with.? If you’re in the business of REST endpoints, Swagger is great.? If you’re building .NET tools, GhostDoc will be a huge help.? You need to figure out what best suits your purposes.
But all that being said, there’s no way I’ve covered every possible approach to API documentation in this post.? So, what are some of the things that you do?? How do you handle accommodating consumers of your API?? Weigh in in the comments!
1 Comment. Leave new
[…] For the SubMain blog, I wrote a post to start a discussion about how people handle API documentation. […]