[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 (generated by Zencaster, so expect some errors). The YouTube video also has a transcript:
00:01.36 - Tom Johnson Welcome to another episode of I’d Rather Be Writing.com. I’m Tom Johnson, and today I’m speaking with Bob Watson. We’ll focus on an upcoming API documentation course that Bob is teaching at the University of Washington. Bob, could you introduce yourself and tell us a bit about your background and plans for the course?
00:29.39 - Bob Watson Sure, I’m Bob Watson. I believe this is my third appearance on your podcast. I’ve been a technical writer for most of this century. The University of Washington approached me about teaching an API documentation course, and I couldn’t pass up such an opportunity. I’ve worked in technical writing at three of the five FAANG companies, having interviewed at three and worked at two. Currently, I’m working with a startup on their documentation.
01:14.37 - Tom Johnson What’s been your experience at these big tech companies like Microsoft, Google, and Amazon?
01:38.94 - Bob Watson I’ve worked at Google and Amazon and interviewed at Netflix a while back. I started my technical writing career at Microsoft, which isn’t part of the FAANG acronym but was significant in my journey.
02:31.63 - Tom Johnson You have extensive experience in API documentation and have been active in the DevPortal Awards as a judge. What insights have you gained from these experiences?
03:07.27 - Bob Watson Dev portals are gaining recognition and improving each year. Judging these awards has been fascinating, witnessing the advancements and challenges in the field.
04:13.60 - Tom Johnson Let’s delve into the API documentation course you’re teaching. Why do you think API docs have been underrepresented in academic programs, and how do you plan to address this gap?
05:20.76 - Bob Watson The University of Washington’s Professional and Continuing Education program approached me last summer. Recognizing the increasing demand for API documentation skills, they wanted to integrate this into their technical writing curriculum. The course aims to bridge the gap between practical skills in the industry and academic offerings.
07:10.60 - Bob Watson The course is designed as an extension of their technical writing program, allowing for specialization in areas like medical writing or, now, API documentation.
08:42.33 - Bob Watson The course caters to those from a documentation background wanting to expand into technical aspects of APIs or software developers looking to enhance their writing skills.
09:22.23 - Tom Johnson Given your unique background in both API documentation and academia, do you find many others with a similar blend of skills?
09:45.19 - Bob Watson It’s rare to find others with a similar career path. My journey has been unconventional, providing me with a unique perspective that I hope to pass on to the next generation through this course.
11:16.81 - Bob Watson Most technical writing academics don’t come from a developer background. This affects the focus and content of academic programs. On the other hand, computer science programs often contribute significantly to research in API documentation.
13:04.32 - Bob Watson The gap between academic research and practical application in API documentation is something I’ve observed over the years. There’s a need for more integration of developer experience and technical writing in academic research.
14:02.67 - Bob Watson Choosing the right API technology to focus on in the course is challenging. We’ll start with REST APIs due to their popularity and support, but the goal is to teach a pattern that applies across different protocols.
17:04.49 - Tom Johnson In my experience, what users often need is not just technical details but clear information about the data returned by APIs. Focusing on this aspect can make API documentation more accessible and useful.
18:53.92 - Tom Johnson Preparing students for the diverse range of technologies in API documentation is a significant challenge. How do you plan to approach this in your course?
19:09.44 - Bob Watson The course aims to familiarize students with REST APIs and general principles of API documentation, rather than training them on specific authoring systems or technologies. Understanding the fundamentals will enable them to adapt to various technologies and tools in their future roles.
21:54.42 - Tom Johnson Why do you think API documentation hasn’t been a more prominent part of academic programs, and how does your course address this?
22:31.63 - Bob Watson The course integrates foundational theories with hands-on practice, preparing students to assess and address the unique documentation needs of different audiences and products.
24:11.73 - Tom Johnson With AI’s growing presence in tech, what are your thoughts on its impact on the need for technical writers in API documentation?
25:39.76 - Bob Watson AI has its limitations and relies on existing content. Understanding these limitations is crucial. AI may need more technical writers to generate original content that it can then reorganize or repurpose.
27:14.00 - Bob Watson Documentation, if well done, should facilitate quicker and more efficient use of APIs. The role of AI in documentation still needs careful consideration and understanding of its capabilities and limitations.
28:44.88 - Tom Johnson How do you envision the role of AI in API documentation, especially in understanding the ‘why’ behind API functionalities?
29:47.96 - Bob Watson A technical writer’s role includes asking the ‘why’ questions, something AI might not do effectively. AI can assist beginners, but its current limitations mean it cannot replace the need for thoughtful, well-crafted documentation.
30:52.74 - Tom Johnson AI tools can help demystify API documentation for newcomers, but there’s still a need for human expertise, especially in more specialized knowledge areas.
34:03.34 - Tom Johnson Discussing the evolving role of tech writers with AI, do you see new functions emerging, such as benchmarking documentation against APIs?
34:53.34 - Bob Watson It would be interesting if AI could identify gaps in documentation, working in tandem with technical writers to enhance the quality and comprehensiveness of API docs.
35:57.44 - Tom Johnson The course you’re teaching is not just about the technical how-to but also includes foundational theory and research, giving students a comprehensive understanding of API documentation.
37:40.96 - Tom Johnson Your blog post about documentation being the canary in the coal mine resonates with the idea that difficulty in documentation often reflects issues in API design.
38:33.10 - Tom Johnson What are your plans for incorporating portfolio development in the course, and how will it benefit the students?
39:10.50 - Bob Watson The portfolio component is part of the course’s ‘secret sauce’. It’s about applying theory to practice and creating documentation that fits the specific needs of different audiences and products. The extended duration of the course allows for iterative learning and practical application.
43:51.41 - Tom Johnson Considering the course duration and content, the cost seems very reasonable, especially in comparison to shorter, more intensive workshops.
44:46.20 - Tom Johnson The course’s structure, focusing on gradual learning over time, seems more effective than condensed, intensive workshops. It allows for better assimilation and practical application of knowledge.
47:29.71 - Tom Johnson My experience has shown that consistent, focused learning over time leads to substantial progress, a principle reflected in your course design.
48:43.10 - Bob Watson While there may be technical challenges, especially with tools like Git, the course is designed to address these through supportive resources and time for practice.
49:12.29 - Bob Watson One final thought: recent trends in documentation usability research are finally seeing practical application. This is indicative of the cycle from research to commercial implementation, and our course aims to be at the forefront of this transition.
52:28.65 - Tom Johnson It’s been great discussing API Docs, academia, and your course. It’s exciting to see these developments in the field, and I’m sure students will greatly benefit from your expertise and approach.
52:51.20 - Bob Watson For more information about me and my work, visit docsbydesign.com. It’s been a pleasure discussing these topics with you, Tom.
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.