[Intro Music]
[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.
[Begin Interview]
[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?
[Johnson] So, if you’re going to get started, I recommend these several things, one is you need to persuade a hiring manager that you’re technical enough. And if you don’t already have a technical background, you’ll have to do something in order to prove it. When I was breaking into the developer documentation field, the job I was trying to get required a lot ofJ avaScript knowledge and knowhow and I had never really done much with JavaScript. So, I went through a course on Linda.com, I took careful notes and I typed them up in kind of a tutorial way, really tried to showcase my ability to learn and understand these concepts and communicate them. And yeah these are just my notes on a course I took but it was enough to persuade the hiring manager that I could learn, that I was passionate, that I was-that I had enough technical aptitude. So, get the technical depth, you could volunteer on an open source project. They’re kind of hard to find, but that’s definitely great if you could do that. Or if you’re at your existing company, you could try to look for more opportunities for more technical projects in-within that context. Maybe you could go out of your way. You could document the innerworkings of something, maybe you work with a helpdesk tool or something. Maybe you’re just a support agent right, in your current role, if you wanted to what you could do is document how to configure and setup that help tool platform, something. You’ve got to build a portfolio of technical samples and these samples need to be persuasive. They need to show that you’re working with code, that you’re articulating complex concepts, that you have some familiarity with a programming language. The companies who are hungry for-for tech writers with developer knowledge will tend to take a chance on you simply because they can’t find a lot of more experienced people. Sometimes these job applications or job requirements will list like five different programming languages and platforms and they’re really drawing a picture for a unicorn tech writer that doesn’t exist right? They basically want somebody who is an engineer who suddenly loves to write and while there are some of those people out here, they are few and far between and so companies have to say, “Okay this person has some level of technical knowledge and they’re willing to learn more,” right and so you can kind of get up to at least the bar level to be considered.
[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.