Tom Johnson: Documenting APIs – Episode 88

Podcast: Play in new window | Download

Subscribe: Apple Podcasts | Google Podcasts | Stitcher | TuneIn | RSS

Documenting APIs is one of the newer jobs in the technical writing domain.

Tom Johnson enjoys the unique challenges of collaborating with and writing for the developers who create and use these Application Programming Interfaces.

He also enjoys reflecting on his work and sharing his insights with his fellow technical communicators.

We talked about:

• his evolution from writing to teaching to technical writing to his current focus on API documentation
• the things he likes about technical writing and how it’s such a good fit for him
• the scope of API documentation and some examples of content provided via APIs
• the difference between documenting self-contained programs vs. APIs, which don’t usually provide a solution on their own
• how developers access and use APIs
• how API designers balance the need for flexible use of their API content with the need to not overwhelm users of the API with too much content
• the differences in assessing and contributing to product design with APIs vs. traditional applications
• the new ways that usability concerns arise and are addressed in API documentation
• how tech writers and developers collaborate
• the differences between writing for technical and non-technical audiences
• his relationships with field engineers, developer advocates, and other customer-facing teammates
• how he works with engineering teams
• the importance of transparency in developer documentation
• how he manages his workflow when he’s supporting multiple teams and products, in particular the importance of being a proactive project manager
• the unique challenges that solo tech writers face
• how he feels more engaged in his career when he’s writing about it
• how his academic background in literary nonfiction has had surprising professional benefits
• how refreshing and fun it is for him to reflect on his professional work and to blog about it

Tom’s bio

Tom Johnson is a professional technical writer in Sunnyvale, California, currently working for Google. When we recorded this interview, he was working for Amazon. He writes a popular blog on technical writing called Idratherbewriting.com, where he explores topics such as API documentation, trends, information design, and more. He also has an extensive online course on API documentation that includes extensive tutorials and other exercises you can follow to build your expertise with APIs, including the OpenAPI specification, Swagger, and more.

Connect with Tom on social media

• Twitter
• LinkedIn

Video

Here’s the video version of our conversation:

Podcast intro transcript

Technical writing used to involve explaining stand-alone programs for consumers and other end users of those applications. Nowadays a lot of computing code is released in the form of APIs – Application Programming Interfaces – which are written by developers for other programmers, not for the end user. This creates a whole new class of duties and concerns for tech writers. Tom Johnson has done both of these kinds of technical writing and is really good at explaining how programmers and writers collaborate to document APIs.

Interview transcript

Larry:
Hi, everyone. Welcome to episode number 88 of the Content Strategy Insights podcast. I’m really happy today to have with us Tom Johnson. Tom is a senior technical writer at Amazon. He’s a prolific blogger at I’d Rather Be Writing. And he also teaches a course, offers an online course on API documentation. And that’s what we’re going to talk about today, is APIs. But first, welcome, Tom. And if you’d like to tell the folks anything more about yourself, please.

Tom:
Thanks, Larry. I’m excited to be on your podcast. I’m based in California in Santa Clara. I’ve been here about seven years, but I’m a West Coast person. I do love to write. I consider myself foremost kind of a writer who steered his career into technical writing and then into API documentation. But at the heart of what I do, even though I love working with tools and learning about different technologies, I do love writing content. I know a lot of people kind of downplay the writing aspect, but creating something from scratch that really unravel something complex in a really clear way is generally fulfilling. And I like doing that.

Larry:
Yeah. I think you exemplify this broad profession of content strategy and that most of us come from a writing background, but things are getting way more technical by the day. And how, because you started as like you were a teacher and did sort of conventional writing kinds of things. How did you end up in the technical world?

Tom:
Well, I did try teaching composition at university level for a while, realized that that wasn’t really going anywhere. You kind of need a PhD to go anywhere in the academia, and the job market was terrible for that. While I was teaching, I happened to also be creating interactive websites for my students. And one of my colleagues said, “Hey, Tom, you would be a perfect technical writer.” This is a colleague who had done technical writing, but I had resisted it for a long time because it just looked so boring, such a sellout, right? To just sort of abandon this passion of more of a creative writing literature sort of career and do technical writing. But when I finally made the jump due to just financial circumstances, I realized that it’s actually quite, quite engaging.

Tom:
The whole tech industry is moving so fast, new stuff that’s coming out every week, and you’re right in the middle of that, and you’re creating content that people want and you’re not trying to sell them something you’re trying to help them. I just found it to be a great fit. And even if you’re not in an academic environment where you’re doing research, you are constantly learning. You’re learning technical things, and that is sort of fulfilling as well.

Tom:
Anyway, I worked in traditional tech writing for a number of years, and there was a lay-off at a company in Utah that forced me to kind of rethink my career directions. And I headed out to California and in the Bay area, most of the documentation jobs are in API documentation, so sort of the natural destination to kind of transition into the API doc world.

Larry:
Because so many of our listeners are not as far along as you in the technical journey, let’s back up a little bit and talk about what an API is, and sort of the transition also. There’s two things in there I want to get to, one is, as I understand, the technical writing and technical communication has evolved from the sort of describing how a program works to being much more involved in a different way. So I’d love to get to that, but also just what an API is and how it works, and its role in modern content and publishing.

Tom:
Sure. I think when most people talk about API documentation, they’re generally talking about developer documentation. About 80% of the time when you’re writing documentation for developers who are building apps or building services, it involves an API of some kind that may or may not be the main part of the documentation, but it’s kind of in there. And an API stands for Application Programming Interface. It’s how companies make their services kind of available for others to build with.

Tom:
For example, this is a simple example I give in my course. Let’s say you have a bunch of weather information, you’re a meteorological service of some kind. You want to allow people to build weather apps, so you provide an API so that people can call and get your weather information and pull it into their apps. That’s kind of the most basic example. Another great example is like when you search for airlines and you want to get flights, you go to services like KAYAK or others.

Tom:
Those sites are pulling in information from other databases and sources in order to kind of present them to you. But all the time, developers work with API to build things. And really, an API kind of abstracts the complexity of a task behind the scenes. When developers are building something, you want to make it easy for them, so you give them some simple way to do a task. And that simple way is usually the API. They put in some inputs and they get back a response or some outputs. And what goes on behind the scenes, it’s often not really important for them to know. They just need to know how they get those outputs and what’s required of them. So yeah, that’s kind of a high level intro to what API documentation is.

Larry:
Right. I’m trying to think of analogous things that happen, because that’s happening all over the place now and a huge amount of what we’re doing. But I think a lot of content strategists operate like in more of an old style monolithic CMS, where everything happens within this one ecosystem. Have you had to go from that sort of monolithic situation to the API world where there’s this sort of like where everything happens in one kind of vertical container to this… The world of APIs is about these little microservices that are connected with APIs. How, I guess, did you have to make any conceptual or leaps in your mind?

Tom:
Well, when I was working in more traditional documentation for mainstream end users, APIs never really factored into that. You had a solution, what it was built with didn’t really matter because you were writing for non developers, or I was writing for non-developers. And one of my first jobs when I came out to the Bay area was for this company that had as their core products, like kind of a little widget that other people would integrate into their website solution, like it was one sliver of something. And that is kind of a more difficult model when you think that, I’m just documenting a piece of a larger solution and this piece alone doesn’t do anything. It’s like how you connect it in with some other pieces that work in harmony for some end goal. That can be kind of challenging.

Tom:
I like to see things end to end, you want to build something and have it run, and do something interesting. But a lot of times, the services that you’re documenting are just like very, very singular in what they do. And it’s not intended to be like an end solution in and of itself.

Larry:
I guess that you’re getting kind of why I wanted to talk to you on the podcast, that conceptual… And I guess that’s why I was talking about the monoliths versus the microservices, it’s this stitching together that’s happening. It’s like the new part of this that you have. And well, I guess, let me ask you how at a kind of a practical level that’s dealt with, are there standards about how one writes in API and shares? How you share information and then how you write the APIs to access it? Or how do you make it all work?

Tom:
Yeah, let me give an example kind of something I currently work with. When people build Fire TV apps, they’ll often work with some APIs around like Alexa. I’m going to set off all my machines if I say that word. So the main job in describing the API… Sorry, the main task in the documentation is really to describe what comes back from the API. And the developer has to kind of figure out how they’re going to incorporate that into their app. You usually don’t have to say, okay, now that you get back this block of JSON or whatever, you don’t explain how somebody then handles it to build their app. That’s sort of dependent on the language they’re using, the framework, the way they’re wanting to use it, which is another aspect of the API doc world.

Tom:
It’s more of a kitchen of ingredients where you say, you can do this, this, this, but you don’t usually have a very prescriptive sequence of how you must use them. You can use the different APIs to accomplish tasks in different ways. It’s much more flexible, whereas if you’re writing documentation for some visual application that has a defined workflow, you might have a more specific kind of tasks like you do step one, then you always do step two, then step three. Anyway, so the API world is more open. You usually don’t go through all the ways that you could make use of the APIs.

Tom:
In fact, a lot of API designers emphasize that you should design your API in a way that you could be surprised by how people use it, like allow for some creativity and flexibility in the way that it’s used that might allow for more robust application of it.

Larry:
Well, that’s so interesting because that’s… One of the big concepts, I think that’s at work in content strategy practice in general is just constantly disarticulating content from its presentation. And a lot of what you were just talking about right there is completely germane to that. And the reason I mention that is that when you think about the way you used to do, like to display weather information on your website, you would have just gone out and sent a reporter to get the interview, however you did it, and would publish that the way that you do it. Whereas nowadays it’s like, I love the way you said, that you have some curiosity about the weather and that your audience wants it.

Larry:
And there’s a bunch of services out there that provide weather information. And so the API is the thing that lets you go like, okay, this service has the right weather information that I want that serves my customer’s needs. And then it’s just the technical detail of figuring out how to implement an API that does that. Is that one way of looking at that?

Tom:
Yeah, for sure. I mean, APIs usually return a lot of different types of information, and some may be more relevant to users than others. Coming back to the weather example, let’s say that I’m building an app and all I want to know is the wind speed. Let’s say I’m trying to figure out the correlation between wind and wildfire or something, right? So that may be the only thing that’s important to me. Now, the API designer has to figure out how they create responses that will have the right amount of information for the user.

Tom:
If you just pack in dozens and dozens of fields that are returned, that’s not going to be a great experience. It’s going to be slow, it’s going to be hard to iterate through, to find the field you want. So the API designers have to figure out the right amount of content that’s going to match with what most developers are trying to do. It’s not as if you can be completely hands off and say, well, I don’t know what they’re going to do with it. I mean, you do kind of have to have an idea so that it’s usable.

Larry:
Interesting. So you’re operating in a common domain and then everybody kind of handles the details both on the supply side and the demand side of these, this functionality. You kind of tailor it to what you’re good at or what your customers need, it sounds like. It’s fascinating, conceptually, I got to say.

Tom:
Yeah. I did want to say just a little point about design. It’s very common when you’re a tech writer creating documentation for a traditional application that you would have a lot of feedback about the design, right? Because you’re using it. You can say things like, “Oh, this button doesn’t make any sense. And this is such a wonky interface.” Or maybe it’s a physical product like, “Oh, this is really awkward.”

Tom:
When you get a code solution, it can be difficult to assess it because usually the tech writers aren’t engineers, you don’t have a background in architectural design and engineering. So a lot of times we’re just struggling to keep up and understand what’s going on. But later when you see how people implement it, you can realize that, hey, there’s a lot of usability aspects here. Like, this was really hard for people to implement. Or, this didn’t have the information people actually wanted, or they had to do some crazy stuff to authenticate it. Or, people are constantly messing up on the parameters.

Tom:
And all that comes back to usability, and that’s a huge field that is sort of ripe for tech writers to become more familiar with like, how do you improve that? Because the ease of use is actually the number one thing that people want from APIs; the the people who consume them, developers who consume them. And the second thing they want is clear and accurate documentation.

Larry:
Which is where you come in. And you’re doing that kind of collaboratively, right? You work very closely with the developers as you develop these, right?

Tom:
Yeah, for sure. I mean, especially if it’s a very technical topic, you may be reliant on the engineers for code samples. Some power tech writers might be creating their own code samples. That’s much less common. It depends on the sort of product and what kind of depth these code samples are. But you would definitely want to get code samples from the developers and you’d want to be able to run them yourself to make sure they work as advertised so that you can describe them. But you are kind of very reliant on engineering input, review, feedback. You do work collaboratively.

Tom:
Often, API documentation has a reference material that’s auto-generated from the source. And that is oftentimes created by the engineers and kind of edited by the tech writers. So yeah, you work hand in hand. A lot of times you’ll have a sample app that they create, or some other extensive code example, and you have to sort of, you document that and you show how it kind of fits in with the documentation you’re providing. You can say, “Hey, here’s an example of this in the sample app,” or make other references.

Larry:
As you talk about that, I’m realizing that both you individually, I’m assuming, and your whole field that made this adaptation over the last 10 or years or whatever it has been from writing most of the tech writing it used to do. I mean, back in the day, you think of the manual about, to help end users use the software. Whereas now your audience is more the developers who are… The API documentation is for this entirely different audience. Was that a gradual shift or did you just all of a sudden wake up one day and you’re writing for developers rather than for end users?

Tom:
It was pretty much a overnight thing when I first started my first API doc job and I realized all my developers are pretty much JavaScript engineers. It is a mind set shift in perspective. Occasionally, there are product managers who read the docs because they’re trying to figure out if it’s going to be something they want. But by and large, you are writing for developers, and that does change things considerably. Whereas with a non-technical user, you might be able to kind of put yourself in their shoes and be like, “Well, I don’t know what this term would mean. And let me define that.”

Tom:
Well, with the developer, it can be really tough. You sort of assume that they’re familiar with a certain programming language. For example, a lot of the Amazon stuff in my space relies on Android, people knowing Android. Because Amazon Fire TV is just like a clone of the Android operating system. So we assume that people are familiar with a lot of things in Android and you don’t want to re-explain something that’s already explained in the Android documentation, but the Android documentation itself is vast. I mean, there’s a lot of different corners of it. And do you just assume that, Oh yeah, my users are Android pros? That they know everything? Or do you assume that they’re kind of winging it in that realm?

Tom:
It’s tough to gauge how much they need to know. And of course the product teams who are designing the APIs often overestimate the technical abilities of their audience. And they just think, “Oh yes, of course, they’re going to know this. If they’re an Android engineer, they will know that, and this.” And then later you often find out that, no, the developers actually struggled with that, or they had a tough time implementing that. It’s like, well, why? Probably because they weren’t as familiar with it as you assumed.

Tom:
On the other hand, in other cases, if somebody is an advanced user, they can kind of just glance at the reference docs and not even need tutorials or other information, and just kind of go to town on building the application. Maybe that’s all they want. They don’t really want to read through details and pages and pages of fluffy copy in order to get the nuggets of information that they need about maybe parameter types or responses.

Larry:
So, are you the mediator, the moderator? Because there’s these varying levels of ability, and awareness, and sophistication, and varying needs, and all this stuff. Are you sort of the linchpin and all that, like figuring out what you need from people?

Tom:
No, no. I mean, sure, in a way you’re kind of the interface, but not really. Usually, in groups that are building solutions for third parties, there’s a role that is like a field engineer or an evangelist, like a technical engineer and engineering type of person who interfaces with the partners to kind of help them build the solutions, to answer questions that interface with them. Maybe they’re called developer advocates, and other places, developer evangelists. So that person is usually the interface with the partners. Of course, it depends on your industry and domain and so forth, but by and large whoever’s interfacing with that developer can help you understand the limits of what that developer’s understanding is around the concepts.

Tom:
And so we sync heavily with our field engineers. We’re constantly kind of getting feedback from them. They will say things like, “Hey, the developers are really stuck here. They’ve found this problematic.” And we’ll focus on that. Most organizations that do have solutions like this, where you’re trying to get others to build with your APIs will have this role, and that’s who you want to sync with.

Larry:
And that’s an interesting… I think people who work on product stuff, that’s sort of the product manager would have that role, that sort of synchronizing, coordinating central role. I guess, maybe, can you speak more broadly just to working with engineers, I guess, because that’s your ultimate audience and that’s who you’re most closely connected with. How closely are you? Are you actually sitting down site… Well, not today in COVID era, but something like sitting down next to each other and working together, or is there… What’s the work process like?

Tom:
Oh, I’m sure it varies highly from company to company. I think, ideally you want to embed yourself within the engineering agile teams. Engineers follow, a lot of them follow great methodologies, usually Agile, Scrum, or Kanban, but they track everything with tickets. They’re very methodical in their approach. They have sprint retrospectives and demos and other kind of daily stand-ups. And in my experience, if you can plug into those, you have a great time.

Tom:
Well, maybe not a great time. I’m saying your experience in providing the documentation goes much better. You build a rapport, they know who you are, you’re kind of in the know. So, if you can embed with engineers and kind of just like go in their same rhythm, that works well. However, I think a lot of people are supporting so many different teams and you sort of bounce from project to project, and it takes developers a long time just to build a small feature.

Tom:
So you probably are wasting your time if you’re attending every meeting through the life of the project. So you’re usually called in when the development team has kind of reached a point where they’re getting near a release, and then you sort of have to work heads-down to write all the documentation. But most developers that I work with, they’re very open. They love to, well, they don’t love to review docs, but they definitely will. They see the value of documentation and they’re very open to being honest and transparent in the documentation.

Tom:
If you have known limitations issues, those are usually – added in a welcome way in the documentation. Whereas other times, if you have more of a product manager, marketing manager, they may not want you to sort of be transparent about all the warts in an application. But a developer’s building, so if there are certain limitations, they have to know, otherwise it’s just going to come back to that engineering team as tickets that they have to solve and resolve and deal with. So I love that aspect.

Tom:
I love being able to be completely honest about how something works or doesn’t work, and engineers are usually great colleagues in that endeavor.

Larry:
Interesting. I love that relationship. And it sounds like there’s a lot of sort of people and process craft in there about knowing, like you said, you don’t want to go to every standup or every… You’re just kind of knowing when to stick your head in. Is that sort of an instinct that you develop over time or . . .?

Tom:
No, I mean, I’ve actually been writing a series of posts about like, what is our method. I’ll point you to some links later, but I think it does take a lot of effort. It depends again, like your organization, but if you are sort of providing docs for 20 different teams, you have to constantly be on the lookout for what’s coming down the radar, like who’s working on what, what are the release timelines? What’s the organization’s strategic goals for the year? What products are planned? And then sort of reach out to these teams and find out the scope of it and sort of what’s expected. Are they writing the docs? Are they not writing the docs? Sometimes teams actually provide their own documentation.

Tom:
So you do have to project manage, as I think is common in many places. But a lot of times, this is nothing new to tech writers, but product teams will wait until the product is almost done before they reach out to tech writers for help. And by that time, you’re like, “Well, I’ve already got this other project I’m working on. I can’t just drop everything and start working on it.” And I definitely try to avoid those scenarios by planning and just kind of keeping aware of what’s going on.

Larry:
Right. It sounds like you said, is 20 an exaggeration or are you actually working on that many different projects at one time?

Tom:
Well, a lot of things are dormant for many years and then they surface. And I’ve been in my current role almost five years, so I’ve seen projects come and go, and teams sort of abandon them after release, but it’s still kind of an active project. And so you kind of own it, but maybe there’s nothing going on there. So you could have a lot of different things going on or you could have periods of downtime, even. That’s kind of rare, but I think it is hard for people to estimate how much bandwidth a tech writer has or doesn’t have. Very few people kind of understand the role of the tech writer amazingly enough.

Tom:
They don’t know if they have too many tech writers or too few, especially in organizations that only have one tech writer. They don’t even have anything to compare against. And in surveys I’ve done, about 30% of writers in API docs are lone writers. This can be very difficult for the writer because just people don’t understand the role. They don’t understand how to work with you when they pull you in. If you’ve got too much, what expectations are around you. You have to sort of teach others, especially even in the review process. You have to pull them along, tell them what you expect. And different methods work better than others.

Larry:
You’re just reminding me. I have several friends in that exact situation where they’re the lone technical documentation person in like an insurance company or someplace. And people are like, “Well, we know need you, but…” That’s a whole other episode, I think, that you’d like to talk about that. Well, Tom, we’re coming up close to time. I always like to give my guests an opportunity. Is there anything last, anything that’s come up in this conversation, or that’s just on your mind about technical communication or anything that you want to share with the folks before we wrap up?

Tom:
Let’s see, what is on my mind. I find that I’m personally more engaged in my career if I’m writing about it. I know that a lot of people love to write who have a tech writing career. Maybe they started out doing creative writing or what. But if there’s one secret, I think, that has helped kind of keep my interest in this career, it is having a blog. I was just writing a post today, or actually this will be another article on my API doc course on documentation maintenance. We’re always focused on the new stuff, and we neglect things that are existing, that are just kind of in our documentation portal. And it’s amazing how things begin to decay. From the moment you publish something, it’s already on its path to becoming outdated.

Tom:
And how do you reverse that trend? Just writing about it and thinking through it, it’s kind of giving me more energy to hack this problem. And I love trying new things out. I love to explore new ideas. A lot of times it doesn’t work out, or I try… Just the other week I was like, I’m going to go sit outside all day. I’m going to work in a park. This is a different thing I was trying to deal with, sort of the work-from-home structure and trying to get out of this mindset, we’re home and work just sort of blend together and in confusing ways.

Tom:
And it didn’t really work, but I had a modification that did kind of work at the end, but even so, the whole act of trying something new, writing about it, it was a lot of fun. And I personally find that the most enjoyable part of being a tech writer and I’d encourage other people who are thinking about, “Hey, I wouldn’t mind having a space to reflect and kind of publish my thoughts on my career.” Start a blog. So many doors have been opened in my career because of it. It’s kind of mind blowing.

Tom:
A lot of times if I’m changing jobs or something, I’ll go into an interview, and the person has already read my blog and they’re sort of already won over to me by the time I even meet them. And I think that’s kind of comforting. I have an MFA from Columbia in literary nonfiction. And a lot of times I look back and think, man, I was headed in such a different direction when I started my career. And now I’m doing tech writing. But it was helpful having that writing background, because it did sort of help me be more successful in my tech writing role.

Larry:
That’s great. And I think that could-

Larry:
No, what you just said could apply to any professional, but you can understand a writer wanting to take a break from writing when they go home. But no, you can do like Tom does and just keep writing.

Tom:
Well, it’s a different mode. If you’re writing documentation, you’re in an explanatory mode, you’re trying to explain how something works. A lot of times, my favorite posts on the blog are in the discovery mode or reflection mode. You start out, you don’t know exactly where you’re going. You’ve got something in your mind, you’re trying to figure out. And that’s sort of the impetus to writing. And that mode switch makes a huge difference, right? I get bored if I’m just documenting stuff I already know. That’s sort of a chore, right?

Tom:
I think part of the fun of technical documentation, honestly, is in that space where you don’t know how something works and you’re trying to figure it out. And then when you finally crack that code, and you’re like, you’ve unlocked a secret. And you’re like, “Oh my gosh, I understand how this thing works. I got it to build, I just needed to do this and that.” It’s kind of a rush. They have some similarities, but basically in the evening, if you can flip that switch and be like, “Oh, what am I thinking about? What is something that I’m curious to reflect on?” It makes writing, at least for me, more refreshing. And it’s more of like a fun time rather than a professional activity.

Larry:
All right. I think the way you just articulated that may help some people get past writer’s block around that, that difference between reflection and explanation. And I love that. Oh, wait, one last thing, Tom. What’s the best way to folks to stay in touch with you to follow you online? Or how do you like to connect with people?

Tom:
Well, my site is idratherbewriting.com and there are links to my API doc course there. I am on Twitter as well @TomJohnson. And I’m also on LinkedIn. So you can engage with me in any of those ways. You can also reach out to me. I have a contact button on my site for email, if you have a burning question. Feel free to reach out.

Larry:
Great. Well, thanks so much, Tom. I really enjoyed the conversation.

Tom:
Yeah. Thanks, Larry. This has been fun.