API The Docs Podcast

Developers are the ones who know their APIs best, but they need an easy documentation process that wouldn’t be too different from the coding lifecycle to produce the technical documentation at scale. Senior technical writer Paula Cristina Vaz outlines the Documentation Framework at Farfetch, created to process markdown files and convert them to Confluence HTML. She talks about the page and document templates that help writers structure their documentation in a standardized way.

Daniel Izquierdo (Bitergia) and Kristof Van Tomme (Pronovix) explained their journey with innersource and open-source communities. They also discussed what a company can do with documentation islands (or silos), and what are the role of technical writers in this process. What is the connection between innersource and documentation? How can we define true collaboration? Resources: Innersourcecommons.org API The Docs Virtual 2023: Feedback, Metrics, Analytics series – Recaps Complexity podcast with Jabe Bloom (Part1, Part2) Developer Portals Newsletter

Business and technical personas may have different skills, and in many cases, they use different terminology. Luca Vettor (Information Architect at Deltatre) explained how Domain Driven Design and event storming create transparent communication between the two personas. What is induced and intrinsic complexity? How could we define the problem space when the customer is in a complex environment and their problems are intertwined? Luca Vettor helped us to answer these questions.References: Luca Vettor’s blog

Why did Fabrizio Ferri-Benedetti (Senior Staff Technical Writer at Splunk) write a love letter to technical writing? How could technical writers create a bridge between the different parts of a company? With an MSc in cognitive psychology, Fabrizio shares a nuanced perspective in his ‘Docs' hierarchy of priorities’ and associated metrics.References: A love letter to technical writing https://isten-ct.com/formacion-comunicacion-tecnica/ https://itcqf.org/ https://passo.uno/docs-hierarchy-of-needs/

Anna Tsolakou (Developer Advocate) and Mathieu Pincovai (Customer Success Specialist) shared with us the journey on how Amadeus for Developers created consistent and clear documentation. We also talked about why the docs-as-code approach is so crucial for them, and how they can create the right documentation for their APIs.

Spotify Senior Developer Advocates Serah Njambi Kiburu and Alvaro Navarro talked with us about the two enemies of developer empathy, and their practices to optimise and scale for the community’s real needs. We also asked why Spotify even needs an API developer portal, and why isn’t it built on backstage? (spoiler alert) They have good reasons for that.

Our guest Emese Hallgató works as a UX researcher at Pronovix Developer Portals. Her education and experience in computer programming and in psychological research open the door to better understanding developers and their needs. How do developers approach coding, and what do they need to reach a state of flow? We talk about the archetypes of systematic, opportunistic, and pragmatic developers. If you would like to deep-dive into the topic more, read Emese’s ‘How do developers learn about APIs?’ article.

In Part 2 of our conversation with Miro's DevRel Lead Anthony Roux and Senior Techwriters Mira Balani and Marco Spinello, we walk deeper into how their respective teams complement each other, and we will also get a detailed narrative from Anthony about their process to aggregate all types of feedback, whether it's a feature requests, bugs, or documentation improvements into one central base.

With our three Mironeer guests, DevRel Lead Anthony Roux and Senior Techwriters Mira Balani and Marco Spinello, we talked about how they joined their teams, what they learnt since, how and by whom their developer docs came to be as they are today, and what two documentarians are to do if they disagree.

Our guest is Anthony Sansone, staff technical writer at MongoDB, who has spent 20+ years in computer hardware, software, and services, specializing in data protection and user security. His experience ranges from startups to large multinational companies. In this episode, Anthony shares his insights about the techwriters’ onboarding and the inspiration you can get from new hires.