Write the Docs Podcast

Latest Episodes:

WTD Episode 15: User research, tech writer stereotypes, and conversations Jul 22, 2018

Show notes

After a short summer break, we've returned to the WTD podcast and taken up our mics again to talk about important doc issues. In this episode, we first chat about assumptions we have regarding our users and the value of doing user research. Basing the discussion on Jen Lambourne's talk at WTD Portland 2018, we talk about ways to capture the user perspective and limitations/workarounds for user research within the corporate domain. Next, we chat about an article by Emily January Petersen on the Make-It-Pretty Philosophy, where the roles of tech writers are reduced to grammar and style editing only, without more substantive updates and revisions to content. Finally, we talk about Tom's research project on healing the academic/practitioner divide and how he hopes his conversation posts will bring both sides more closely together.

WTD Episode 14: Humanizing your documentation Mar 22, 2018

Show notes

In this episode, we chat with Carolyn Stransky, a journalist and JavaScript developer living in Berlin, about ways to humanize documentation. We discuss dilemmas with transparency in docs (the balance between honesty and negativity), ways to avoid gendered language (including whether to correct workplace misuse of 'he'), strategies for achieving plain language and clarity (such as by reading your content out loud), the term 'user' and alternatives, how to develop empathy for your audience, why terms like 'simple' and 'easy' are problematic (even in Marketing), tools for identifying insensitivity and complexity in docs (Hemingway, Alex), what makes content sound truly human, and more.

WTD Episode 13: Postman for API development and docs — Interview with Postman Founder Jan 22, 2018

Show notes

In this episode, we chat with Abhinav Asthana (founder and CEO of Postman) to explore how Postman, a REST client, can be used to create, collaborate, and publish API documentation. If you work with API documentation, you've probably used Postman to make and test API requests. But you can do also a lot more with Postman. You can embed Run in Postman buttons that contain collections of requests that users can load in their own Postman clients (perfect for getting started tutorials). You can collaborate with engineers on the requests and documentation by syncing collections across a team account. And with just a few clicks, you can also publish and host your documentation through Postman, complete with code samples in multiple programming languages. Check out Postman's API Network to see many ways different companies use Postman in their documentation.

WTD Episode 12: Founding ideas behind Write the Docs Dec 13, 2017

Show notes

In this episode, we chat with Eric Holscher (WTD cofounder) and Mikey Ariel (WTD Europe organizer) about the Write the Docs community itself, including origins, founding ideas, goals, challenges, trends, and roadmaps for the community. We dive specifically into idea of diversity of roles (and the term 'documentarian'), the way open source principles inform the community's core values, balancing individual freedom to contribute on one's own terms with the expectations of the WTD experience, and more.

WTD Episode 11: Combining Forces for Documentation Sources -- Exploring the Mozilla Developer Network's Web Docs project Nov 27, 2017

Show notes

In this episode of the Write the Docs podcast, we chat with Kadir Topal, product manager for Mozilla Developer Network Web Docs project, about how they manage this large body of documentation for web developers. The MDN project provides standards-based documentation around web development topics (for example, HTML, CSS, and JS) intended for web developers, with the goal of producing consistent experiences for users across browsers. Kadir gives us an inside look into the challenges, goals, and roadmap of this project.

WTD Episode 10: What's going on in our lives as documentarians and product owners Oct 10, 2017

Show notes

In this episode, we talk about what's going on in our lives as documentarians and product owners. Chris talks about challenges in collaborating with reviewers in efficient ways. Google Docs works great for gathering comments, but it isn't so good for storing source code in a manageable format. Also, it seems that every company/client has their own preferred toolchain around reviews, and it's hard to know the best approach to take. Jared talks about the ebbs and flows of managing products in the gambling space, and the challenges around benchmarking, performance testing, and uptime demands for the products he manages, especially during the Melbourne Cup. Tom is excited about the docs-as-code milestone reached at his work, where his team can now build and deploy Jekyll directly from the server through commits to an internal git repo. This publishing efficiency allowed their team to get rid of an old, archaic CMS publishing process that was slowing writers down.

WTD Episode 9: Chatbots in Documentation Sep 19, 2017

Show notes

In this episode, we're joined by Ellis Pratt from Cherryleaf to talk about chatbots in documentation. What are chatbots, and how can you incorporate them in your docs to enhance the user experience? Are chatbots the next evolution of wizards? What are some examples of successful chatbots? How does one get started using chatbots in documentation? Are there chatbot services you can leverage inexpensively to try them out? These are some of the questions explored in this podcast.

WTD Episode 8: Stack Overflow's Documentation Failure and Open Source Challenges Aug 22, 2017

Show notes

In this episode, we're joined by Beth Aitman to talk about what happened with the Stack Overflow Documentation Beta. What did Stack Overflow try to do with documentation, and why did they abandon the effort? Why did their effort to crowdsource docs fail but succeed so well with forums and niche content? Additionally, we discuss the difficulties of creating good documentation with open source projects. A recent survey found that incomplete or outdated documentation is the number one issue with open source projects. Why? What makes it so difficult to create documentation on an open source project?

WTD Episode 7: Let the robots do the work Jul 03, 2017

Show notes

In this podcast, we first explore the flourishing community of technical writers in Poland, discussing why the tech writing scene in Krakow is taking off so quickly and what trends this young tech writing community is embracing. We're joined by special guest Pawal Kowaluk, a Polish tech writer who runs SOAP (a tech comm conference based in Poland). We also talk about automation and robot takeovers of tech writing jobs. How are machine-assisted technologies enhancing or displacing technical writers and their work? Given the increase in automation, is tool expertise becoming more or less essential to thrive as a technical writer?

WTD Episode 6: Metadata and UI copy Jun 06, 2017

Show notes

In this episode, we explore the role of metadata in documentation and how it can be used to classify topics and assist in the discoverability of information. We're joined by special guest Eva Jackolis who explains a strategy for metadata used in German mechanical engineering documentation. We also discuss involving tech writers in UX copy and the challenges inherent in influencing UI copy, product naming, and working with UX designers and product teams.

Our TOPPODCAST Picks

Follow Us

Stay Connected

Related Podcasts

Links

Stay Connected