Skip to main content
API The Docs Podcast

API The Docs Podcast

By API The Docs
Our guests talk about their insights and experience as documentarians. We bring advice from behind open and closed developer portals, ideas on what new learnings you can aim for, and recent experiments from the field of API documentation.
Listen on
Where to listen
Apple Podcasts Logo

Apple Podcasts

Breaker Logo

Breaker

Castbox Logo

Castbox

Google Podcasts Logo

Google Podcasts

Overcast Logo

Overcast

Pocket Casts Logo

Pocket Casts

RadioPublic Logo

RadioPublic

Spotify Logo

Spotify

Currently playing episode

Insider's advice on actions your tech writers can take to create quality API documentation

API The Docs Podcast

1x
A good design is not about how something looks, it's about how something works - Interview with Liam Gallagher and Jake Eastham from Barclays
Today our guests are Liam Gallagher (UX Designer/API Platforms) and Jake Eastham (Front-end Developer and Accessibility Champion) from Barclays: “It's very easy to get caught up in aesthetics, you want to design something that is really cool and you think it is amazing.. You actually want to show it to everyone, but you completely messed up the accessibility part. As I matured, I realised that good design is not about something that looks good, but how something works. A good design is naturally inclusive. “ “An accessibility champion is someone who fosters within their environment, within their own team, while being aware of the different accessibility challenges you have and why we are designing and developing our products, what is the importance of it. “ Join us for an inspiring conversation with the two times winner of DevPortal Awards in the Best Accessible Portal category. The hosts are Laura Vass (Editor of Developer Portals Newsletter, Co-Founder of Pronovix) and Anett Pozsár (Senior Technical Writer, Pronovix).
32:45
April 29, 2021
Creating a fully self-service API program - Interview with Alvaro Navarro and Anthony Roux
Meet the Developer Relations & API product management team on Amadeus for Developers - Open API Product for the travel industry. Our guests are Alvaro Navarro and Anthony Roux. “Building trusted relationships is actually what matters in our job.. and empathy is what makes the big difference. Put yourself into the shoes of the other person, that's how you're going to learn how they use your product. And that's how you're going to be successful.“ How has Amadeus innovated a framework and a new set of self-service APIs, where developers can connect in a matter of only three minutes? How have they scaled up and automated all the processes to make the onboarding as smooth as possible? Why is testing and user centric feedback, API Governance and product management support important when creating solutions that provide the best developer experience for your API consumers? Tune in to hear more. The hosts are Laura Vass (Editor of Developer Portals Newsletter, Co-Founder of Pronovix) and Anett Pozsár (Senior Technical Writer, Pronovix).
35:38
April 7, 2021
Tech writing for software engineers - Interview with Barry Rosenberg
Our guest is Barry Rosenberg, technical writer at Google and co-author of courses Technical Writing One and Technical Writing Two. At the beginning of his professional journey, Barry was starting out as a teacher for a smaller group of undergraduate students at MIT. How did he become a teacher of a highly scalable class for thousands of engineers at Google? How has writing fiction helped him to write better technical courses? Join us to learn more about his inspiring career and the courses he created: How and why have these courses been developed? Why is it valuable to teach tech writing to engineers? What are the prerequisites and skills required to become an efficient technical writer? What new tech writing courses are currently being created at Google? The hosts are Laura Vass (Editor of Developer Portals Newsletter, Co-Founder of Pronovix) and Anett Pozsár (Senior Technical Writer, Pronovix). Sources: Barry Rosenbeeg - Spring Into Technical Writing for Engineers and Scientists Overview of technical writing courses at Google 
35:54
March 24, 2021
Inclusion and Accessibility - some suggestions from fellow documentarians - Interview with Ilona Koren-Deutsch
We ask Ilona Koren-Deutsch about the Women in APIs initiative, and her advice on how to diversify a team. We talk about considerations to ensure accessibility for your content, and what can propel the company-wide use of a conscious inclusive style guide. Where should you be channel agnostic as a techwriter? Does feedback need feedback? Tune in to find out, where to get mentoring and support, how to take an active role in empowering other women in the industry, and how to create equal opportunities, regardless of gender, language barriers or other impairment issues. The hosts are Laura Vass (Editor of the Developer Portals Newsletter, Co-Founder of Pronovix) and Ádám Balogh (Technical Writer at Pronovix). Sources: Women in APIs 
34:39
March 12, 2021
Where Product Marketing Meets the Docs – Interview with Liz Couto
We are talking with Liz Couto, Product Marketing Manager at Shopify, about the role of marketing and an amplifier, where the CTA is often pointing to the developer documentation. How did Shopify empathize and empower in 2020 with the exponentially growing community? Can there be too many communication channels, should you let go of some if ever? How do the many teams involved work in concert on Shopify's products and what feedback loops have they built into their docs? The hosts are Laura Vass (Editor of Developer Portals Newsletter, Co-Founder of Pronovix) and Anett Pozsár (Senior Technical Writer, Pronovix). Music: Virgill - Its over now (CC)
37:57
December 4, 2020
Feedback Management & Documentation Workflows - Interview with Uwana Ikaiddi
“It’s a misconception to think that documentation is a solitary endeavor” says Uwana Ikaiddi (Documentation Manager, BigCommerce). Getting involved in cross-team discussions as early as possible while preparing for a project is a key element of a documentation workflow. But how do you avoid death by collaboration? The interview also explores how you can empower your audience to communicate with you in the most efficient way possible, and in what ways you can triage and address internal and external feedback. The hosts are Laura Vass (Editor of Developer Portal Newsletter, Co-Founder, Pronovix) and Anett Pozsár (Senior Technical Writer, Pronovix). Music: Virgill - Its over now (CC)
33:09
November 4, 2020
Intentional Jargon and Technical Documentation – Interview with Erin McKean
The Good Docs Project aims to create open source documentation templates, and most recently an information architecture template too. Erin McKean, one of the central orchestrators behind the Good Docs Project, is our guest for this episode. We talk with Erin about why it is so important to intentionally include jargon in your technical documentation and where to do that. She shares her practice on curating a project documentation wishlist to keep the future focus going, and why and how to get documentation treated as a key core feature of a product. The hosts are Laura Vass (Editor of Developer Portal Newsletter, Co-Founder, Pronovix) and Anett Pozsár (Senior Technical Writer, Pronovix). Music: Virgill - Its over now (CC)
37:24
November 2, 2020
DocOps and Automation to the Delight of Technical Writers! - Interview with Paula Henk & Patrick Hammond (Adyen)
What are the main principles a documentation team operates on in a fast-moving industry? How to adopt DocOps? How does a documentation team decide on what should be automated? What is hard to automate? What is the point when you should not neglect the human eye? These are key questions that we try to find answers to in this interview with Paula Henk (Technical Writer) and Patrick Hammond (DocOps Manager) from Adyen. The hosts are Laura Vass (Editor of Developer Portal Newsletter, Co-Founder, Pronovix) and Anett Pozsár (Senior Technical Writer, Pronovix). Music: Virgill - Its over now (CC)
32:47
October 22, 2020
Remote Onboarding and Technical Writing: Things We Can Do Better
How can you onboard new technical writers when your office just turned into remote-first? This podcast episode focuses on the mistakes Karen Sawrey (Contract Technical Writer) made and the issues she’s encountered and solved when joining a team of tech writing colleagues. The interview also touches upon documentation security and testing, the importance of guidelines, and how the technical writer role is transforming today, in the time of remote working. The hosts are Laura Vass (Editor of Developer Portal Newsletter, Co-Founder, Pronovix) and Anett Pozsár (Senior Technical Writer, Pronovix). Intro music: Virgill - Its over now (CC)
33:32
October 14, 2020
Developer-friendly API Documentation with Milecia McGregor
“When you’re working on APIs that developers use, they need to know exactly how to use them. Great documentation is the way to do this & it gives development a chance to make things more user-friendly.” In this podcast, Milecia McGregor (Developer Advocate, Conducto) reviews why API docs are important and she also shares some tips about how to manage their development cycle.
34:20
October 7, 2020
The Evolution of a Documentation Platform - Interview with Fabian Rodriguez (Vonage)
Vonage’s developer platform journey started in 2017. Little did they know the impact that some of their design decisions were going to have now. In this interview, Fabian shares how the platform evolved over the years, what challenges the team needed to overcome and what new features are in the pipeline. Tune in to get some tips about separating the prose from the code, and find out what developer advocacy is necessary for the success of this new tool chain!
36:01
October 1, 2020
Insider's advice on actions your tech writers can take to create quality API documentation
At the 7th API The Docs Virtual event Michelle Fredette, technical writer at New Relic and Chris Cowell, Oregon-based technical trainer and writer presented on the issues of onboarding writers with different knowledge gaps and how to solve them with 8 hours of training. Uwana Ikaiddi, Developer Documentation Manager at BigCommerce explained the significance of external and internal audience feedback, and gave guidance on how to improve API documentation by them. In the Q&A panel of the event, they reflect on their talks and provide further insights on: Do you also train your developers on how they can document for themselves? What would you recommend for people who want to change career-path from development to techwriting? Is there a need for anti-personas, i.e. people who aren't specifically the core audience of the API documentation but might need to consider when writing the docs? How to build trust with your internal audience? Can you speak to techniques who are getting collected external feedback to the appropriate writers on a large writing team? Does teaching developer students technical writing support a faster and more efficient on-boarding process in the long run?
21:15
July 3, 2020
Dev-first API products, API explorers & Microservices
At the 6th API The Docs Virtual event Egan Anderson, head of developer experience at Galileo, explained ways companies can prioritize developers’ needs. Larry Kluger, lead developer advocate for DocuSign, presented how to create easy to use graphical drag & drop tools for creating and trying complex API requests. Michael Haberman, co-founder & CTO at Aspecto, explored maintaining API production while using microservices to collect data and by that, help development and testing phases. In the Q&A panel of the event, they reflect on their talks and provide further insights on: What are the milestones in API documentation processes? How to make sure all advocates are being heard during the development? How to boost morale & excitement in an internal audience when it comes to API initiatives? Which is a better approach: design-first vs. code-first? Why use Blockly library for API exploring? Is there a need to develop own libraries for open source APIs? How to make your APIs self-documenting? Which are the instances when reducing the number of your services is recommended to maintain your system?
21:04
June 19, 2020
Dev Doc Trends w/ Tom Johnson
On 27th Tom Johnson, senior technical writer at Amazon, presented his comprehensive research on how API documentation trends differ from other tech comm trends. In the Q&A panel, he reflects on his talk and provide further insights on: What methods does your team use to estimate time for creating a documentation? How to improve the dynamics inside and outside of your documentation team?
11:06
June 8, 2020
Change management on large & complex documentation sets
On 13th May in the API The Docs virtual event Sarah Day, technical writer at LaunchDarkly, shared how you can incorporate API documentation in the big picture for overall efficiency in your organization. Riley Siebel, director of Developer Experience at C3.ai, and Mark Winberry, director of US Operations at Pronovix, presented a case study on providing a good DX with docs-as-code regardless of your system’s complexity. In the Q&A panel, they reflect on their talks and provide further insights about the following topics: Do you have any advice for tech writers in a larger organization who must get buy-in at multiple levels of leadership? How do you get understanding and support from other departments to help drive advocacy when getting buy-in? Have you done any research about where to host an API's docs compared to the API itself? What kind of documentation tool did you use before you moved to docs-as-code?
13:32
May 21, 2020
Defining Top API Use Cases and How to Meet the Goals of Your API's Audience
On 6th May Steph Mills from Splunk shared how you can create the best possible golden paths through the API woods, and how to reduce the need for users to stray from the path into the wilds. Bob Watson from AWS explained how you're able to meet the practical aspects of customer goals with your API documentation, and how to measure how well you meet them as your API and customers evolve. In the Question-and-Answer session after their presentations, they reflect on their talks and provide further insights regarding customer oriented API documentation and API use case documentation. Enjoy!
17:20
May 13, 2020
Minimal Viable API Documentation and Developer Experience
On 22th April Mike Jang from GitLab explored what an Minimum Viable Documentation is for RESTful APIs. Jenny Wanger explained that the way you name, design, and structure your APIs has a huge impact on usability. In the Question-and-Answer session after their presentations, Jenny and Mike reflect on their talks and provide further insights. Enjoy!
21:24
April 30, 2020