Inevitably, during our first discussion with prospective clients about documenting an API, we are asked if we can do “something like Stripe’s”. Unfortunately, until recently, our response was “not really” because Stripe had created its own tool to publish API documentation.
Now, thanks to the hard work that people have put into open source projects like Redoc and the Open API Specification, we can finally say “Yes” to these requests for API documentation. Previously, three-column, responsive, web-based documentation was only available as part of an expensive subscription to a development platform or as a customer-developed portal, but as REST APIs have become more and more popular, the tools to support their development and use have become more widespread. We can provide three-column API specifications with a basic quick start guide hosted on our client’s own website. For the client, that means no recurring fees and no commitment to a development pipeline that may not be a good fit for its company.
For many of our clients, we are able to use their existing API documentation (with some editing), translate it into the Open API specification, and add any additional content (for example, how to build a basic application). At that point, using Redoc, it’s a simple matter of generating a website that looks something like this:
With this three-column format that organizes navigation, technical specifications, and examples, it’s easy for developers to find and understand the features of your API. And, as we all know, “easy” often means they, the developers, are more likely to use your API over one that isn’t. Clearly, as they say in corporate parlance, a “win-win”.
Objectivity tends to be one of the core values of technical fields. The fundamental laws of physics dictate the properties of microprocessors, and chemistry defines the properties of the materials we use. These methods make up the API, determining how that application behaves and what it is capable of doing. The way that people interact with technology, however, is anything but objective. They bring a lifetime’s worth of experiences that guide their behavior and frame their expectations for both what the technology will do for them and how it will perform its duty.
From touch screens of various sizes, to Microsoft Kinect™, Google Glass, Fitbit, and Square, we’re seeing a panoply of new devices that broaden both what technology can do and how we interact with it. This explosion of new interaction technologies has even created a bit of a hiring frenzy for interaction, user experience designers, and human computer interaction specialists whose job it is to design how exactly we are going to get all these new toys to do what they are supposed to. Dreaming up fantastic new ways to interact with all this fancy technology is one thing, but how do those dreams become applications, and how do people know how to use them once they get them?
Paul Clifton is a Ph.D. student in Digital Media at the Georgia Institute of Technology. He has been an on and off technical writer with Shoap Technical Services since 2007 and is currently working in interaction and user experience design at Intel.
Recently, I helped my friend update his resume. I’d helped him make a brand new one a few years before, and it had been an extremely painful process, so when he asked me to help update it, I nearly just said no. To my surprise, the draft he sent me proved that he had been paying attention when I had originally explained the rules for making a good resume, why they were the rules, and why following them mattered. His grammar and spelling still weren’t very good, but grammar and spelling are the easy part. Clearly communicating complex information by meeting the expectations of the reader is the hard part, and I was happy to see that he had pretty well taken care of that.