[Podcast] Breaking ground: New API documentation course at UW, with Bob Watson
Listen here:
To learn more about Bob Watson, see the following:
- Bob’s blog: Docsbydesign.com
- Bob’s Linkedin profile
(Note: This is not a sponsored post.)
Course details
The API documentation course is part of the Continuing Education program at UW, intended for students in the technical writing program to specialize after completing their main course work, or for professionals with at least two years of experience. For details, see Specialization in API Documentation.
Topics covered in the podcast
Here are some topics we talk about:
- Bob’s background working in API documentation at big tech companies like Microsoft, Amazon, and Google. (For the latter two, I was a colleague of Bob’s.)
- The University of Washington reaching out to Watson to teach a new API documentation course.
- The rising demand and need for API documentation skills training.
- Details on the 14-week evening course Watson is teaching.
- Fundamentals that will be covered like understanding developers and APIs.
- Using AI with API documentation, whether to learn some of the technical aspects of APIs or to assist with writing.
- Incorporating hands-on practice and students building API documentation portfolios.
- Challenges related to varying technical backgrounds and troubleshooting over an extended period of time.
- Bob’s goal to ground students both in theory as well as practical skills — the balancing act.
- The importance of an extended timeframe (14 weeks) for thoroughly learning complex skills, allowing the learning to “soak.”
- How API documentation that’s hard to write can be like a canary in the coal mine, revealing flaws in the API design.
During the podcast, I mentioned an alternative acronym to FAANG (Facebook, Amazon, Apple, Netflix, Google) that describes big tech: “TAN MAMA”: Tesla, Apple, nVidia, Meta, Alphabet, Microsoft, and Amazon.
I also mentioned this post from Bob’s blog: If your API is hard to document, be warned.
Transcript
The following is transcript of the podcast. (The transcript has been cleaned up a bit by AI to make it more readable.) The YouTube video also has a transcript:
Tom: You’re listening to another episode of I’d Rather Be Writing. My name is Tom Johnson and today I’m talking with Bob Watson. We’re going to be focusing on an upcoming API documentation course that Bob is teaching at the University of Washington.
Tom: Bob, can you introduce yourself a little bit? Tell us where you’re based and what you’re planning with the upcoming course.
Bob: Yeah, so I’m Bob Watson. I think this is my third time on your podcast, but it seems like we’ve been around for a while. I’ve been a technical writer for most of the century and the University of Washington reached out to me and asked what I would think about teaching an API documentation course. I thought, well, how could I pass that up?
I’ve been doing technical writing at three of the five FAANG companies. I interviewed at three of them and worked at two. Right now, I’m working for a startup doing some documentation for them and it’s never a dull moment.
Tom: I was just reviewing your LinkedIn profile to get the latest. You’ve worked at Microsoft for a number of years, you worked at Google, you worked at Amazon. Those are three of the big tech companies. I’ve heard a new acronym for them instead of FAANG - TANMAMA. It stood for something, but I can’t even remember all the companies. Maybe I’ll look that up.
You’ve got a lot of experience working at companies doing API documentation. You’ve also been pretty active in the API the Docs Dev Portal contest. You’ve been a judge there for two, three years?
Bob: I think last year was my fifth time, which seems really hard to imagine. It’s been an interesting ride to watch how dev portals are starting to come into the spotlight and get better and better each year. It’s amazing what the contestants have been able to do. Each time it gets harder and harder to judge because they get better and better. Last year’s was a pretty close pack.
Tom: I did that just one year and I realized what an immense time commitment it was, as well as how difficult it is to judge documentation and the different criteria you can use. It’s a lot of thought and effort.
I’m sure that gives you a lot of insight and experience about trends, what’s going on, and prompts thought about what actually makes for good API documentation. You’ve got a well-rounded and broad view of the industry beyond just the places you’ve worked.
Bob: The contestants have been increasingly impressive and it just leaves me honored to be in a position to judge them. I don’t feel worthy to be in a position to judge them. They’re working way harder than I am.
Tom: I want to focus a little bit more on this API course you’re teaching. Historically, academia hasn’t really offered API documentation courses. This has always been something that has irked me. I always feel like this is a huge topic, it’s important, it’s what a lot of people want to upskill in. Why isn’t it more common in academia?
If we’re trying to close the gap between what practitioner skills practitioners want to learn and the academic offerings, why not offer it? How did you finally help bring this course to be?
Bob: Well, last summer they reached out to me and I thought it was kind of an odd call, but sure, let’s see what they’re interested in. They had all the magic words like API documentation and training technical writers. I thought, well, I can’t think of a higher calling than that.
We’ve been working on it since last summer with increasing intensity. This is offered by the Professional and Continuing Education site of the University of Washington. Of all groups, they are definitely focused on what’s practical. I guess after 20 years, API documentation is being recognized as being practical. We’ve known that for a lot longer than that, but it takes a while for the awareness to kind of bubble up and reach critical mass.
I thought, sure, this is nothing like an interesting challenge to catch my interest. I guess they’ve recognized that it’s an increasingly in-demand skill. They also have the technical and professional writing courses in the Professional and Continuing Education department. This is kind of a specialization in that.
After you get the general technical writing skills, you can specialize in medical writing if that’s where you want to head, or now API documentation if that’s where you want to head. I don’t know if we have any other things in the pipeline, but it’s essentially an extension of their technical writing program.
Tom: Got it. I was looking at the program details again and I see that you first either have to complete the technical writing curriculum or have a couple of years of experience as a technical writer. Is that right?
Bob: Yeah, and I think one of the questions you sent was about what it’s hard to know where to start with API documentation. I started as a developer, so I kind of came at it from that side. I had to learn the writing side.
That’s what we’re trying to address with the prerequisites. You have to bring a little bit of one or the other and then we’ll kind of shore up the other half. Either you’ve got the technical figured out and we’ll work on the writing, or you have the writing figured out and we’ll work on the technical.
That’s pretty much the first half of the class - to sort of level reach a kind of a level in both categories that we can then proceed into the documentation of APIs.
Tom: You’re somewhat unique in the field. We talked about how you’ve been a technical writer working with APIs and developer docs for a lot of companies and a lot of years. You’ve also been an academic. You’ve taught at Mercer and had other academic experience. You have a PhD and you’ve done a lot of research.
Do you think there are many other people like you who are both API documentation skilled writers with developer kind of background as well as academics?
Bob: No, because most people pick one and stick with it. That’s something I’ve not been particularly inclined to do. I haven’t met too many people that have my sort of similar career path. I think there are a few out there, but I definitely took the windy road to get to where I am.
It gives me the blessing and the curse of a rather unique perspective that I’m not sure I’ve been able to communicate effectively with others because it’s hard to relate. But over the years, I think I’ve identified what is going to help pass this on to the next generation. That’s what we’ve been working on while developing the class - to find the messages that will resonate with the different backgrounds so that we can kind of raise them up from wherever they’re starting.
Tom: Let’s dig into this a little deeper. Why is it that so many other academic programs in tech comm don’t really offer API docs and why do so many tech comm academics kind of focus more on maybe theory or broader topics and shy away from more of a technical domain?
Bob: That’s a loaded question. In my experience, I think very few percentage-wise of the technical writing academics come from a developer background. Most come through kind of a liberal arts in English or some background on that side of the campus. You stick with what you enjoy. That’s what got you tuned to technical writing and through the PhD program or whatever.
They just kind of pursue that. One of the things you need to survive and come out on the other side of a PhD program is a pretty clear focus that you can commit to for your whole life, for five years or so. I don’t think there are many people on the technical writing side that are going to do that for API documentation, except me.
The computer science field, some of the research in API documentation, in fact, I think most of the research that I didn’t write comes from the computer science side of things into the technical writing. I think I wrote a blog post about that in 2018. I haven’t looked it up to see if it’s continued, but they don’t cite any technical writing resources in their papers because that’s not what they’re familiar with. I would imagine, I don’t know, I haven’t talked to them to ask why.
That was one of the comments I just like, you know, it’d be nice if they talk to some of the writing people who actually study what works from a reading comprehension perspective while just looking at all the tools to automate. It’s like you can automate the documentation, sure, but is it going to be readable? Well, that’s for another person to figure out.
Tom: Yeah, that it is interesting. I remember some years ago just looking for research, tech comm research in about API documentation best practices, other topics, and just coming up empty-handed in the typical journals where tech writing topics are published, you know, like STC’s journal, for example.
Only really finding things in computer science journals, the IEEE type publications, and so on, which I know also has a professional publications journal. But typically, yeah, it seems like most of the research that I found that resonated with me was done by people who were computer scientists.
That’s weird, but yeah, that was my experience. When I would look for research or articles to reference, they all came from computer science schools from various parts of the world. It’s still very good research. I mean, I’m not knocking it by any means. It’s just always been this weird conundrum.
API documentation has consistently been a trending topic and has always been something that a lot of people want to cement their skills in and develop. And yet, it’s really been something that hasn’t had more attention and focus in academia. That’s what’s always perplexed me.
Your answer about how people start in one path and they have to specialize and commit makes a lot of sense. I’m really excited about this course because it’s like broadening that. You’re the perfect person. You’ve got this background that marries all these different disciplines and brings it together.
Tom: Why don’t we jump more into the course itself? APIs is a broad topic. You’ve got REST APIs, which have received the most sort of attention recently, but there are a lot of different APIs. How do you possibly narrow down this course into the right API technology that people will benefit from learning?
Bob: Yeah, I don’t know that there’s a right technology. There’s a current technology, there’s a popular technology, but each one’s right for whatever it’s done. Over the years, I’ve documented for a variety of different interface technologies or protocols. Once you’ve done a few, they all sort of fall into a pattern.
I want to focus on that pattern, to recognize the pattern and identify the aspects of a REST API, because we’ll be using REST APIs since that’s the most supported and the most common. It’s kind of the one that everybody seems to understand if you’re talking to somebody else.
We’ll start there, but we’ll spend, I think, one class or one lesson on, okay, so what are the elements of the REST API and what do they look like in other protocols? Once you understand kind of the ins and outs, what does the reader want to know? Because that’s always the fundamental question.
What do they need to know to be successful with this particular API and what does that look like? Once you can kind of break it down into those pieces, then if it’s one API or another, the differences aren’t so intimidating.
You can say, oh, well, that’s the input, that’s the parameter, that’s the response, that’s what it returns. Each one does it a little differently, but the general principle of identifying what to document is pretty much consistent throughout the different protocols I’ve worked on, at least.
Tom: You know, I started out doing a lot of REST API stuff back when I was working for a startup. When I had first switched courses or switched gears into the API documentation world, I was working for a startup and they had a REST API. That kind of introduced me to the world and I started developing some training and so on on REST APIs.
Then I got hired at Amazon and the whole method was different. It was all Java APIs. I wasn’t in AWS, you know, I was in the devices org. In the devices section, you want to have APIs or you want to have code that’s running on device and so on. It’s kind of a different world.
For five years, I was just working on Java-related APIs, occasionally a cloud API in there. Then at Google, it’s kind of the same story. For a lot of the APIs, they were Java-based APIs and only recently have I been returning to documenting more REST APIs.
But even the REST APIs, it’s not as if people write the spec in the OpenAPI contract. They don’t follow… At these big companies, they seem to have their own kind of process. It’s difficult to try to prepare somebody and say, “Hey, you want to document an API, this is how it is.”
It’s like, no, it could be totally different from one company to the next. You could be focusing on C++ APIs and that’s probably totally different. You might be using Doxygen or something. How do you prepare students for this wide variety of technologies that seems kind of overwhelming to just tell people, “Yeah, you could be working on five different programming language-based APIs or something totally different from that.”?
Bob: Well, hopefully they aren’t doing it all at the same time, at least not to start. Yeah, I think you described something that mirrored my career experience in that I don’t think I’ve ever used the same authoring system twice. I’m not sure, I’d have to think about that. REST API, I think, has happened at more than one place. It’s been around long enough for us to run into each other a few times.
Yeah, it’s like everything’s different. Teaching them a REST API or with the spec and all that, I think would be doing them a disservice. They would train them for one job, but that might not be the job they’re looking for or the job that’s offered to them.
I haven’t worked on the same authoring system either. To complicate the technology matrix, there’s the technology you’re documenting and then the technology you’re using to document that. That’s been different everywhere I’ve gone, I think, pretty much without exception.
Learning how to do markdown in some publishing system, pick your favorite, would train you for a job. But if you don’t know how to generalize that, you’ll only be able to have one job. That’s the reality.
What I want to try to do in the class is to say, okay, we’re going to use REST APIs and we’re going to use kind of GitHub Pages because that’s convenient. We’ll try to identify, okay, well here’s what it’s doing that other systems would do. They might do it differently, but as long as you know what to look for… How do I edit? How do I publish? What’s my version control? How do I make changes and keep track of them?
If you know the questions to ask, then learning the new system becomes a lot less intimidating. It’s like, okay, well, what do you use to do this? What do you use to do this? Okay, great. Now I can get to work.
If it’s “Where’s this command?” and they say, “We don’t have one of those,” then it’s like, “Okay, well, I don’t know what to do now.” That wouldn’t be a very effective education.
I’m trying to go for teaching the… I guess my philosophy reflects my background. I want to teach enough theory to know the questions to ask. I don’t want it to be heavily theory-based because they’re not going to be doing research, at least that’s not what I’m preparing them for. But I want them to know where this comes from, because it’s going to change.
If they know the foundation of the why behind the method, then when the method changes, they can go back to the why and say, “Okay, well, how would we do it in a different method and still answer the same question?”
Tom: I think that sounds like a great approach. In my career, I think when I started out doing API documentation, I was thinking that it was more technical than it turned out to be.
I got very focused on thinking that, oh, I’ve got to learn Java, I’ve got to understand C++, I’ve got to understand this code sample because everybody wants code samples. But as I’ve been in this field for a while, I’ve realized that what users really want, rather than really technical details, they want information about the data that the API is returning. They want to know, they want good descriptions of this content.
Usually, the engineers who describe the data, usually in the source files and so on, provide kind of hasty, confusing descriptions of the data being returned. So I’ve really tried to focus more on that.
I don’t really get a lot of questions and feedback from partners about how to actually use the API. It’s more like, “Hey, we have questions about the data that you’re giving us.” And that’s not really a hugely technical topic. It’s much more accessible to tech writers.
Now, I have another question. As AI is becoming such a trending topic, I’m sure it’s spilled over into your thoughts on API documentation and what to teach. What would you say if somebody said, “We don’t really need tech writers because users can just sort of plop in API reference code or reference-generated Javadoc or something and autogenerate code samples and get an understanding of it. You want to understand this method and what it returns, you don’t need nice documentation, you just need to point somebody to the source, they throw it into an AI tool, and the AI tool kind of writes the documentation dynamically.” Have you ever heard that kind of question and trend? What do you think of that?
Bob: Well, honestly, I think that’s a bit uninformed. I mean, everyone talks about AI like it’s this mystical oracle of knowledge, but all that comes from somewhere. That’s one of the contentious aspects of ChatGPT, for example. It’s like, well, where exactly did that come from and did you pay for that? Are you using my knowledge without my permission?
As a content creator, as an author, that’s a bit of a concern. It’s like, am I going to be writing stuff that someone’s going to take and then use and then they aren’t going to need me anymore because they stole it or took it without paying, if you want.
So that’s a concern that a lot of other artists have had their art repurposed or ingested. I guess I’m not quite sure what the verb is. But again, back to the more practical point, it’s like, well, we’ll just have it read the code and write the docs. Well, so the reading the code can tell you what it does, but it doesn’t tell you why or it doesn’t tell you how.
Knowing what it does is like, well, I could read the code and see what it does, and if I can’t, it’s probably not code that I want to use if it’s that complicated or that incomprehensible. But it’s the… I think the thing to take away from the “what about AI” question is just understand what its limitations are.
If it needs content in order to reproduce content, well, where does that content come from? I thought there was an article, and I wish I looked it up because I’d love to quote it, that said that AI is going to need more technical writers to do that very purpose - to get the original content that AI can then reconstitute, repurpose, and reorganize. That might be a useful purpose, in that if you give it enough good source content, then the machine can find different ways to interpret that for different questions. Okay, that might be a valuable use. I don’t know if we have that yet.
We might have that for some of the older technologies that have been around for a while that have lots of content to ingest. But you know, it always comes back to the why and how. Is this doing something that’s going to actually give us what we want? Sometimes it is, like when you’re using an established documentation set and the AI is finding the topics for you so that you don’t have to or you don’t have to work for it. Okay, that might be an advantage.
But it can’t find it if it doesn’t exist. So when the AI can start looking at content and tell you why it’s doing that, why did they put, why did they invent that method, why does that method return this particular object? Okay, well, that might be interesting. I don’t know that we’re there yet, but it can certainly tell you that it does that. But then reading the code, if reading the code is your documentation, that’s disappointing.
You know, because anybody who’s read the code knows that that’s not the shortest path to the destination. Yeah, because a lot of code is so modular and so microscopic that it’s hard to see a big picture until you’ve looked at all of the code, and who has time for that? You’re supposed to be using it, not reinventing it.
Documentation, if it’s done right (not every documentation is done right because I did a study on that), if it’s done right, it should make the path to being able to be productive quicker. Now, if it doesn’t do it, then documentation failed, but that doesn’t mean you don’t need documentation, it just means you need better documentation so that it can do the job.
But yeah, when it comes to AI, if it’ll do what you want it to do, and do it right, by all means. But make sure that that’s the case. Certainly interesting, all the different aspects of this, of uses and misuses and abuses and so on. It’s kind of like watching a movie unfold, all the different things that are happening. But it’s bleeding-edge terrain right now.
Tom: Coming back to an earlier point you made about the why and how, like the AI tool might tell you what’s happening but not why, that’s super important. You know, just yesterday, I was updating a release note engineers had sent me and it basically said, “Hey, the value of this field is now one.” And I was like, “Okay, why did we make that change? What is the significance of this? What problem did we solve here?” And there’s absolutely no information about this. It was just like, “Hey, this value is now going to be one.” And I’m like, “Okay, we need to unpack the why.”
No AI tool, I even plugged this into BART wondering if it would magically reveal an answer, it didn’t. But yeah, unpacking that why really requires a lot more discussion with the engineers and understanding.
I’m just to ask the question, and I think that’s kind of an unrecognized value of the technical writer. You would think to ask that. AI would say, “Okay, fine, it’s one.”
There’s another aspect that I think is kind of exciting for students with AI, because API docs have typically been very intimidating to a lot of people, especially without the programming and developer background. I think the AI can really make it understandable, especially for general introductory knowledge that a person might need. You know, like what is this class, what is this method doing?
It can really help somebody who’s stumbling around in this field just to get oriented. I’ve used… man, I’ve just been blown away by how helpful AI tools can be in some other areas. I was trying to understand some tax stuff the other day, it’s that time of year, like capital gains taxes and all kinds of details about the financial world that I don’t fully understand. And it really helped me, you know, but these are introductory novice questions.
I even was solving a networking problem last night. I was like, I plugged in my… I plugged in an Ethernet cable directly into my, to an adapter, to my computer, and it was slower than the wireless speed. How could that possibly be? And after like five minutes, it was like, “Oh yeah, your network adapter doesn’t support gigabit Ethernet speeds.” Like, “Oh, of course.”
But applying these same things to API docs, I can see where a technical writer who’s stumbling through a new language or something could really kind of make sense of things, enough with enough kind of explanations and simplified understanding of things to be productive.
Bob: Yeah, no, it’s good at that. I mean, just even like talking to ChatGPT a few times, it does have a way to present complex topics in simple terms. But if you already, you know… but it… so that would help the beginner and help them get started, I could see that.
As far as helping the expert, it’s like the answer then seems kind of like, “Really? That’s not an answer. What are you, crazy?” We asked it when it first came out, we asked it, “Okay, how would you land an airplane?” And it went on and on, “Well, you should just get close to the runway and touch down.” I was like, “Really? That sounds like a good idea. I was thinking I’d crash.” But no, that’s not landing, that’s crashing.
And so the answer was just lots of words in that general direction. Yeah, and so I wouldn’t take flying lessons from ChatGPT just yet. But again, that gets back to its limitations. For someone coming into it, it can certainly speed the ramp-up time. But at some point, you have to kind of let go and ride the bike without the training wheels.
But if it can get you to that point faster, then great. Again, it all comes back to, is it going to do what you want it to do, and know how, know when it can’t help you anymore so that you don’t rely on it too much.
But you know, we’re still getting used to it and it’s still changing. So it’s going to be kind of an adventure to see how that goes. I think that for scenarios where you move outside of basic knowledge and get into more specialized knowledge, which is mostly what we end up documenting at companies, the technique that I find most helpful, I believe, is called the retrieval-augmented generation, where you supplement your queries with some kind of big chunk of text that it can then kind of draw upon to find more expert answers. And what is that chunk of text? It’s usually documentation of some kind.
So the need for this documentation is still very much a reality, even if people are supplementing their interactions with AI to kind of parse through your documentation.
Bob: Oh yeah, and those combinations of kind of manual and automatic technologies are going to continue to evolve as we get better talking to the AI and the AI gets better at talking back to us. So it’s going to be… what works today is going to be different tomorrow. It’s going to be “hang on tight.”
Tom: Yeah, no, the next big phase is just right around the corner. I saw that OpenAI is now officially launching their custom ChatGPT store, or custom GPT store, you know, which like, my immediate thought is, “Oh, great, we can have a GPT trained on a specific manual and ask questions about that.” And that’ll be interesting to see if that becomes a trend.
Anyway, what would be nice, just to follow up on that point, is it’d be nice to tell us what documentation we’re missing. You know, “Well, I can explain this, but there’s a hole here.” Like, “Oh, so you know, so again, so you can work together.”
If it’s just going to repeat what I say, like, “Okay, well, that’ll get us somewhere,” but that’s not going to find the holes. That’ll just repeat what, you know, what I felt we needed to say. But if it can say, “You know, well, this is explained, but this isn’t,” and then like, put it, file a ticket and say, “Could you explain this better so I can explain it better to the people asking?” I think that’d be cool. You know, so I think there’s ways for us to develop the partnership.
It’s not just all what can it do for us, but you know, how can we work together to make it better for everybody? I think, you know, without going too far down this AI topic, I really think that, but I think one role that tech writers will start to develop is like benchmarking tests for documentation against an API.
I’ve been wanting to try this to kind of think, “Well, what are maybe a hundred questions that users would probably want to know with this API?” And let me see if an AI tool can answer those questions based on, you know, this big body of documentation. And then where it can’t, my role might be to go through the docs and add content until it can answer those questions.
I don’t know, I haven’t come to that point yet. Part of the problem is that API documentation has so many different individual pages. Like a Javadoc has 250 pages for one of my APIs, which is actually a small API. So how do you package up all of that information? How do you create a crawler, for example, that will index all that and feed it into an LLM? That seems a lot harder.
I mean, fortunately, most API documentation is, or should be, relatively structured. So it has a form that should be relatively easy to follow. Again, bad documentation, it’s always going to be bad documentation. But if it’s structured in an organized sense, where you have some hierarchy of classes for all the reference topics and some organization of how-to and the conceptual explanation content, I would think that it would actually be easier because it does have at least the opportunity to apply a structure to help, you know, and computers like structures and organization. And technical writers do too. So we should get along fine.
Bob: That reminded me of a post actually you wrote that is probably one of my favorite posts you’ve written. Oh, you had a post on your blog a few years ago about how documentation is often the canary in the coal mine, where if a tech writer struggles to describe and explain your documentation, if the tech writer finds it hard, it’s probably a sign that there’s something wrong with your API, that some part of the design might not be well thought out. And so, yeah, I usually think that when I’m writing something, I’m like, “Why is this so confusing?” And I’m like, “It’s not you, Tom, it’s not me, it’s a bad design, because it’s confusing.” You’re right on point, you know.
Tom: Anyway, let me… let’s steer back a little bit into this course. So it’s starting in March and it’s an evening course, runs for 14 weeks. But one of those details are all on the UW website. One of the details that you’ve put there is you’re going to help students put together portfolios. Can you talk a little bit about this approach? How are you going to… how will you do the portfolio part? Like, are these going to be fictitious projects, real projects? Are they going to be… are you going to have them document something real or something technical around their house? What’s your… what are your thoughts on the portfolio?
Bob: So that’s some of the secret sauce I’m still cooking. So I, you know, some of the foundations that I believe strongly, after studying and doing this for long enough, is there are fundamental principles you need to understand. You need to understand the audience, you need to understand how developers attack documentation and what their motives and goals are so that you can meet them there.
You have to understand the structure of the documentation to support those goals. And then, you know, you have to understand that documentation or API documentation serves a bunch of different purposes depending on where the reader is in their cycle with your API.
You know, the kind of the acquisition and adoption cycle of the documentation. Some want to know features to, at the early stages, they want, “Will this solve my problem? Will it, can I apply it to my problem? Can I be successful with it?” And as they go through those stages of acquisition and application, they have different interests and goals.
So as long as you can address those, then it doesn’t really matter what you document. But because each product is going to have sort of a different way to, different take on that, because you’re going to be writing about different products to different audiences for different tasks.
So understanding how to kind of measure the fit for the jacket, you know, you have the arms and the chest and the collar and all that. So once you can do that, then you can make the jacket that fits. You know, you can just get one off the rack that might be a little bit long or a little bit tight, you know, but it still looks like a jacket. Okay, well, that’s one approach.
But you know, to get the kind of the premier documentation experience, you want a good fit. And so we’ll be learning those skills at the kind of the first half of the class, through kind of theory and practice. And the reason I stretched the class out for 14 weeks, we had talked about it shorter, but I don’t think that’s going to work. We need more time for this. Some of this stuff just needs time to bake. You know, you have to like do it, think about it, come back, do it again, and think about it.
You can’t do that in a seminar. A seminar is just sort of like absorb the dump of… absorb the knowledge dump, you know, and then take some of that away with you. But API documentation is a hands-on skill. And so, you know, it’s like learning woodworking or mechanics. You need to get in there and just, you know, get your hands dirty.
And so I wanted to have time to kind of have learned the theory, see the theory in practice, put it into practice, and then have time to do your portfolio, which is sort of you driving solo at that point. And you know, I figured, because of the technical challenges… I think we talked about, you know, trying to get everybody’s computer with the software installed and learning…
Get, teaching Git has always been… I know, kind of a personal demon of mine. But I… we’ll see if I have the answer this time. But I’ve been using and trying to get other people to understand how to use Git for almost 10 years now, and I don’t know that it’s ever been easy. It has gotten easier. The tools and the support, it’s a lot more widely used, so there’s a lot more support for it in the world. So there’s a lot more resources to draw from. So I think maybe Git should be a little easier.
But you know, I’m… I’m planning, I want to allow time so that we have time to wrestle that to the ground. But the, I guess, back to the point is, you know, like I said, API documentation is a hands-on skill whose skills are founded in theory. And so I want to be able to kind of develop that understanding and then give time to iterate and practice and review. And okay, we’ll be peer-reviewing the portfolios.
And so I think that’s… I think that’s kind of what makes it worth the cost, because it is expensive. But I want to make sure everybody gets their money’s worth. And so I want them to be able to take away, you know, have had the chance to do lots of practice so that it’s not just a portfolio, it’s not just a static document, it’s kind of an artifact of a whole process with a story behind it.
And so I think that’s… that’s what you can’t get with self-study. It’s a lot harder to do with self-study.
Tom: You know, coming back… you said something that jumped out at me. You said it is expensive, but I don’t really think it is expensive at all. It… It says… Oh, good. Can we put that in our promotion?
Bob: That didn’t come out right. That makes me sound like I’ve got expensive money coming out of my pockets or something.
Tom: Okay, so the cost of the course is $1,795, right? $1,795 for 14… It’s a lot more expensive than free. Now, keep in mind, before the pandemic, I was actually teaching one-day API documentation workshops for like, from 9 to 5. Something I charged $500, $600 per person for these workshops. It was a one-day thing, in, out, at the end of the day, done, done in one day. And usually about 15 to 20 people. I only did like three of these, okay, because the pandemic just decimated everything.
But that was… I thought at first, I thought, “Gosh, who’s gonna pay $500 for this?” But there were lots of people. Honestly, I think it’s a lot more lucrative to tap into the professional technical writers with corporate budgets for training who just want like a one-day exposure.
But you’re providing 14 weeks, multiple… you know, a lot of class sessions. That’s a lot of time for somebody to kind of soak in knowledge. I think that’s a… that’s a steal of a deal. You know, if I… if I offered somebody 14… I don’t know, how is it? One class a week? Two classes a week?
Bob: Yeah, so it’s… it’s three hours a week.
Tom: Three hours a week. So that’s like the equivalent of, you know, about a week… a week of seminars, a lot of time. And yeah, if I were to offer somebody a full week of like, API documentation workshop instruction, like immersively, I’d charge probably more than that by far. And yeah, go ahead.
Bob: Yeah, I was just gonna say that. But I think it’s like baking a cake. You know, you could turn the heat up to 500 and get it done in 5 minutes, but I don’t know that you’d want to eat it.
I think there’s an advantage of doing it over a period of time where, like I said, you have time to let it soak in and then come back with a question, and then have, you know, still have 12 more classes that you could get that question answered in.
I… You know, I think there’s a place for the one-day seminars or the one-week seminars, and I’ve gone through those and they’re really intense. And I don’t know how much I remember a week later, but, you know, depending on how they… how they teach it.
But I think… I think soaking it over time should be a more effective learning experience than just trying to, you know, open the fire hose and take a drink. Because there’s a lot to it. You know that there’s a lot to it. I’m impressed you could squeeze all that into a day.
Tom: Well, yeah. Yeah, I… I agree that, like, there’s a lot to it and soaking things in over time is definitely the best way to learn something technical.
I remember when I was preparing for some interviews at Google, I knew that they had a like a tech writing or a technical test and task. And so I was really trying to like, learn Java. And every time I’m in the job market, I’m always like, relearning Java, if you’d like. Because you have to know one programming language good enough to persuade them.
And so I would… I would set myself a goal that I would like, try to do a certain number of like, pomodoros, like 20-minute focus sessions every day. But over the course of like, two, three weeks, you know, doing a couple hours a day, it was amazing how much progress I had made.
And yeah, if I had tried to cram in a whole Java crash course in one day, it would have been overwhelming. So I… I do like your setup and the time frame. I think it’s great. And you’ve got the patience and the expertise to answer so many questions.
I… I don’t know how much patience I would have to answer the “how do I install this” question. Like, just even getting Git installed for people on Windows with different machines and different versions was just kind of like a nightmare. And then, yeah, a lot of technical troubleshooting. Hopefully, hopefully that’s not a big issue.
Bob: I’m expecting… I mean, I’m hoping it doesn’t happen, but I’m expecting there to be challenges. So I’m… I’m doing lots of installation videos to help distribute my wisdom across the class a little bit easier. Yeah, but… but yeah, it’s… it’s… There’s all kinds of places where things could get challenging. But hopefully with time, you know, that’s the other reason I want to have more time, is so we don’t let that kind of derail the course. Yeah.
Tom: Well, Bob, we’ve talked about a lot of different things. Is there any other topics that you want to bring up in this discussion about API docs and academia and the course and so on?
Bob: No, I guess the… the only… I guess closing thought that I’d have is that in going back to the last API the Docs Dev Portal event, they were talking about… they had a presentation by a couple of the people that work for them about documentation usability. And they were citing some of the papers that I cited.
And so it reminded me that it’s… I’ve finally seen this come to pass. It’s like, there’s always… what is it? It takes 20 years to go from research to, you know, commercial application. And I’ve been doing this about 20 years. So it’s like, ah, just in the nick of time.
You know, because the studies they cited, I cited, and they were done in like 2004 about the kind of developer personas. And that was done by research at Microsoft in 2003, 2004. And so I cited those in 2012, and now they’re coming back and being represented or presented in 2024.
So, so yeah, we’re right on schedule. That’s great. So your syllabus will include some theory. It’s not just going to be like a technical how-to. It’s going to be some foundational stuff. And these are the papers that you’re kind of incorporating in.
Bob: Yes. You know, there’s various papers. There’s… my favorite that I like to cite was done on how developers go in and out of the documentation, you know, trying to do a… you know, some technical programming task. And how they kind of bounce in and out, and how they… how they… Because there isn’t a whole lot of research that’s been published on kind of how developers interact with documentation.
We make lots of assumptions, but there’s only been a few papers that I’ve seen that have published that. And so that’s… you know, every… every developer audience is a little bit different. And so you want to speak to yours, but it’s… it’s always good to start with a kind of a base of, well, it’s probably somewhere in here, you know, and then we’ll figure out kind of where… which direction they go.
You know, our audience, you know, they might be more advanced, they might be more specialized in something. So we want to take advantage of that. But we could start out with, well, we know they’re going to be in here somewhere, and so those are kind of the things I want to teach.
I want to teach them how to, you know, come in and assess the situation based on the existing research and theory, and then zero in on their audience and their product so that they can write the best documentation for them. And like I said, that’s everywhere I’ve been, that’s been slightly different.
And so, but… but knowing that difference and taking and speaking to that is what will set the documentation apart that, you know, that you’re working on. Yeah.
Tom: Great. Well, hey, it’s been a pleasure talking to you and hearing your thoughts. I enjoy having you as a colleague. You know, we’ve run into each other in so many different parts of our career, from the blogosphere to the API the Docs to Amazon and Google and so on.
So I’m really excited to see you opening up these doors into API docs in academia. And I really think that students will benefit from it. So thanks again, Bob. I’ll… I’ll add links to these things in the show notes. And if people want to find out more about you in general, where should they go?
Bob: Oh, just docsbydesign.com.
Tom: Docsbydesign, yeah. All right, I will definitely point them to that. Okay, thanks, Bob.
Bob: Great. Thank you. It’s good to talk to you again.
Note: Some summary content in this post was AI-assisted.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.