[Ryan Weber] Welcome to 10-Minute Tech Comm. This is Ryan Weber at the University of Alabama in Huntsville, and today I’m pleased to welcome Tom Johnson to the show. Tom Johnson is a technical writer at the 41st Parameter and he also runs the blog, I’d Rather Be Writing, and today he’s joined us to talk about API documentation, and why he considers it one of the best opportunities for technical writers in the field.
[Weber] Welcome to the podcast Tom. We really appreciate you joining us today to talk about API documentation and you know this is something that I’ve seen more frequently lately in technical communication and we’ll talk about that. But to begin with, can you just give us kind of a really brief overview of what is API documentation?
[Johnson] So an API stands for Application Programing Interface, and this is a type of developer documentation. APis are interfaces that allow two different systems to interact, usually a client interacting with a server. A typical example might be, let’s say you have a weather feature on your site, that weather feature is going out to some kind of weather API, getting some information, and pulling it back into your site, and that’s just one example of thousands that, that you see. Everything from YouTube, Facebook, Twitter, their all powered by APIS, but also things like search and pretty much any feature on a site and sort of in beyond, in applications. So, any type of information that you’re pulling into your software, your platform, is usually coming from an API of some kind. And so, the API documentation is essentially just describing that API: the requests you can make, the responses that come back, and how you make it all work. But you’re really writing for an audience of developers and that’s what makes it unique. The API documentation is just one type of developer documentation. The shift to writing for developers instead of end users, as we often call them, is huge because the material’s a lot more technical. Your audience doesn’t like to read, they want quick answers, they want to see code samples, they want to be able to copy and paste code samples and make them work immediately, they want reference applications. It’s a different sort of mindset, and it’s sometimes it can be a lot harder to test out the things and make sure they work. You have to set up environments, really probably get help from engineers to make sure you’ve got everything up and running properly. But it’s a lot more fun at the same time because you really dive into this sort of software programming domain and this whole world opens up where you can develop expertise; you learn a lot. It’s not just learning that you-you throw away when your project ends, like with a particular gooey application that you may be documenting. It-there are concepts and principles that you carry over from one project to the next.
[Weber] How does it differ, API documentation, you know a lot of technical writers are probably familiar with writing what we might consider more standard user help, how does this differ? You mentioned you know the audience is developers, it might be more technical, are there other ways that it’s different than what we might be used to writing?
[Johnson] In end user docs, you typically have very defined tasks that, that you can do in an interface; 1…2…3 kind of steps. But with developer docs, and especially API docs, you usually have what’s, what’s called a set of endpoints that lists kind of interactions that you can use with the API, the types of information that you can get back. There’s lots of different ways you might use that information. You might do things radically different from one environment to another depending upon what you’re trying to achieve. So, you tend to have less task-based type of topics and more kind of reference topics and you have tutorials, like a “Hello World” tutorial would walk a developer from the first step to getting some basic content out there. And the “Hello World” might cover like how to get an authorization key, how to construct a basic request, how to, I don’t know, get the information and put it somewhere so that it says “Hello World” on a page or something. But it would walk through the whole array of what you have to do, and you might provide tutorials for-for common business scenarios that kind of resemble the task, sort of stuff in user doc, but by-and-large, I mean developers are creating something. They’re creating applications, they’re creating ways of doing things, they’re not necessarily following a very defined tasks in a gooey, it’s kind of fun because people are doing more creative work and they’re doing more sophisticated things
[Weber] Very good and it seems like this has, in the technical writing world, has gotten a lot more attention in the past few years. You know I’ve seen it more, more workshops and more blogposts, and that kind of thing, why do you think it’s garnering more attention?
[Johnson] Definitely end user documentation is on the way down. I’m not saying it’s going to disappear, but the market for it is a lot shallower than the market for developer docs. Developer documentation is a super hot field because it’s hard to do. It’s hard to do well. I mean a lot of engineers try to write developer doc and it ends up being blinded by the curse of knowledge, where they’re just blind to all the assumptions that they’re making, or they just don’t want to write it and so they do a hasty job right? And so it takes somebody who’s got a lot of patience, who’s got an incredible level of detail, who can spot areas that are going to be challenging. So this is a skillset that’s in high demand, especially in Silicon Valley, almost every company is moving towards an API of some kind to allow people to integrate their services. The web is moving towards this mashup of interconnected services really. I’ve heard it referred to as like a device-mesh where one device is kind of interacting with these other devices as you move into this internet of things where everything is connected. And how are they connected? Well the different APis are allowing these different systems to interact. Now if you’re going to build a website, in the past you would probably use a platform like WordPress, Droople, Joomla, that’s kind of like this all in one platform, you just enable different extensions, plugins, or whatever, but you’ve got this massive system. Well I think websites nowadays at least are moving towards this cafeteria style model where if you want service, like a search, you might integrate a search API from somewhere like Algolia or Swiftype. You want an e-commerce solution, you integrate an e-commerce API, maybe you’ve got Stripe integrated there. You want some other features, you just pull in from different APIs and a lot of products are like you’re not a generalist, you leverage specialist services through different APis for what you want, and so because of that model and because everything is online: the software, the service model, the API, especially the rest API is really becoming the default way that companies are making their information assets available to consumers. So, it presents an incredible opportunity for technical writers. I mean there are a lot of opportunities in this space and it’s a fun, rewarding, and challenging one. I enjoy it more than end user documentation quite a bit and I would encourage people to look into it.
[Weber] So if you were a technical writer that wanted to get started in this, what kind of skills would you need and how would you go about getting started?
[Weber] Thanks a lot for talking with us about this today. I know this-do you have a lot more material on your site? What resources do you recommend if people want to learn more?
[Johnson] Yeah, my site is idratherbewriting.com and you can go to the top navigation bar there, click “API Documentation,” I’ve got a whole course of how to get started, it walks you through curl, Postman, JSON, like all the different stuff you would use. There’s also some courses on Udemy, u-d-e-m-y.com, by Peter Grunebomb on API Technical Writing that are good. There’s an article on the STC Intercom last year or couple of years ago now where we did a whole issue on API docs. If you search my site for that STC Intercom issue on API Doc, you can get the article-you can get the whole issue for free. There are lots of other resources but those are several I recommend.
[Weber] Terrific. Well thanks so much Tom, we really appreciate it and best of luck in the future.