API The Docs Podcast

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.

API The Docs podcast logo

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

03 July, 2020

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?

Dev-first API products, API explorers & Microservices

19 June, 2020

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?

Dev Doc Trends w/ Tom Johnson

08 June, 2020

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?

Change management on large & complex documentation sets

21 May, 2020

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?

Defining Top API Use Cases and How to Meet the Goals of Your API's Audience

13 May, 2020

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!

Minimal Viable API Documentation and Developer Experience

30 April, 2020

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!