Introduction to Web API Documentation
Web API documentation is a fast-growing field for technical writers. Web APIs are how data is passed on the internet between mobile devices, web apps, and servers. They are considerably simpler than programming languages, and relatively easy to learn how they work. This course covers structured data (JSON and XML) and how to document it, as well as REST requests and responses, and how to document them. It will also provide a short introduction to Markdown, the simple markup language. No programming experience is required. Bring a laptop or tablet that will allow you to type easily and browse the web. A text editor like Notepad++ or SublimeText is recommended, but not required.
About the workshop leader
Peter Gruenbaum is the president of SDK Bridge, which specializes in API documentation. He founded the company to bring together his love of technology and writing. He has worked as an API writer to describe APIs for eCommerce, automobile traffic prediction, electric utilities, cameras, tractors, and cat humor sites, just to name a few. He has published four online courses on writing API documentation on the Udemy platform. Peter received his BA in Physics from the University of Chicago and his PhD in Applied Physics from Stanford University.
Date and Location
Friday, January 20 2017, 10 a.m. – 5 p.m. at Mission College, Santa Clara, California
Be sure to locate our volunteer in the parking area so you get a parking pass for Friday!
$125. Lunch is provided.
For tickets, see our Eventbrite page.
An interview with the presenter
by Li-At Rathbun, TC Camp Roving Reporter
Three minutes of talking with Peter Gruenbaum is all it takes to get excited over API documentation. Or maybe it’s just one minute. Either way, I’m hooked and can hardly wait for the hands-on workshop!
Here’s what I learned from talking with him:
Li-At: What attracted you to API documentation?
Peter: I started out as a physicist and then I got into software development. I was working as a software developer during the dot com boom and then bust. The only work I could find was as a contractor for this tiny company—and I just hated working there. I was desperate to go somewhere else.
I got a call from a recruiter who asked, “Hey, can you write? We need someone who can write.” I’ve always enjoyed writing, so that got me a one-year contract as a programmer/writer at Microsoft. And I discovered I enjoyed the challenge of communication—of trying to take this very, very technical information and figuring out how to explain it in a way that was clear to people; stuff that I understood pretty deeply because of my software-developer experience—just trying to figure out how to make it make sense.
And then after doing this for many years, I decided… I always had this interest in starting my own company, and it felt like there’s a big need for this. There’s just not that many people who have that really strong technical background and can write well. I decided to create a company based around it. So it’s been about 8 years now and it’s a tremendous variety of work, and I get to learn about all these different technologies and then write about them.
I think it’s a combination of getting to use my technical skills and my writing skills—it’s enjoyable. And also the variety and the challenge of figuring out how to explain these complex concepts in a way that people will understand it.
Li-At: Who should attend this January 20 workshop?
Peter: It’s going to be very much an introduction workshop. I see it as useful to technical writers who are interested in this field. I’m focusing just on web APIs. There’s a few different types of APIs, but the web ones are the ones that I think are the simplest and easiest to get started on.
So it’s for technical writers who are interested in this area. They might have had some experience in this area, but I don’t expect them to be experts in this area. If they know how to program, that’s great. But it’s certainly not required.
Li-At: So is this workshop for people who are interested in web API or is this also an introduction to API in general?
Peter: I think it [web API] is a good stepping stone. It’s a great way for people to try out and get a sense for it. There’s some writers who get it and enjoy it, and there’s some who find it’s not that interesting. So it’s a way to get your feet wet with web APIs, and if you like that then the next step is that you can learn programming and get into the other stuff.
Li-At: Why should technical communicators care about API?
Peter: There’s a bunch of reasons. One, I think it is a very interesting field and you do get to work with the cutting edge of technology. And you really get an understanding of what’s going on in the background. When you use a Facebook app on your phone, you don’t realize that all these messages are being sent back-and-forth between Facebook and the server. And just sort of getting an understanding of how this “API economy,” as they call it, is happening. I think that’s a really interesting thing to get involved in. So there’s that aspect of it.
There’s the aspect, too, that this kind of skill is very much in need right now. So if you’re looking to get to the next step, I think this is better paid than a lot of technical writer work. It’s more in demand. It’s just a really useful skill to have if you’re looking for technical writing work.
Li-At: What’s the one thing that all technical communicators should understand about API?
Peter: Well, I guess it’s not that different than other kind of communication, but I think it’s especially true of API documentation. That the people who are creating it are very close to it and that they need somebody coming in from the outside to have the perspective to say, “What is this going to be like for somebody new looking at it” and to create the documentation that orients people and explains how it works.
So that’s the one thing: be aware that your outside perspective is valuable.
Li-At: Okay, so this is TC Camp. So my next question is what’s your favorite camping spot?
Peter: I live in Seattle. So my favorite camping spot is on Mt. Rainier.
Interviewer note: If this picture that Michael Matti took while gazing out his tent is anything to go by, who can blame him?
Li-At: If you could take one person camping, or one technical communicator camping, who would that be?
Peter: There’s lots of people I met who I like in the technical communication field. I don’t want to single out just one person.
But in general, I always talk about how Nikola Tesla—how is so popular and in now—he was my childhood here. This was back in the 1970’s, when nobody had heard of him, and I just thought he was the greatest, most interesting person ever. And it’s been funny to watch his popularity grow over the decade. …He’s probably not the camping type. But who knows what he would invent along the way to make camping a more interesting, better experience.