Write The Docs Podcast

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.

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.

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.

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.

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.

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.

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.

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?

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?

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.

In this episode, we explore where technical writers belong in an organization. Is tech comm best placed within engineering, marketing, product management, or another group? We also talk about strategies for doc navigation, in particular, the merits of inline links and/or sidebar navigation, using a post from Every Page Is Page One as a starting point. Are hierarchical sidebar menus still useful, or are they a relic of the past? Finally, we provide details about the upcoming Write the Docs conference in Portland, and Chris mentions his new book on responsive design.

In this episode, we talk about continuous integration strategies for docs (for style, screenshots, and REST calls). We also dive into discussions around docs as code, including how to encourage developer collaboration, how to stay informed about the code updates that developers make, and more.

In this episode, we discuss top technical writing trends for 2017. Chris discusses how more technical writers are interacting with support groups, and even being embedded within support departments. Jared discusses how docs are being planned for earlier in development cycles, as more product managers are seeing the value of docs. Tom talks about how more technical writers are treating documentation as code, and the challenges inherent in developer tools and workflows.

In episode 2 of the Write the Docs podcast, we explore how to help users find what they're looking for in your documentation. We talk about various tools for findability: search, tags, faceted filters, sidebar navigation, inline links, related links, terms/glossaries, and breadcrumbs.

In this first episode, we introduce the co-hosts, the podcast theme, and chat about a few articles. The four co-hosts include Jared Morgan, Carlee Potter, Chris Ward, and Tom Johnson. We're located in Sydney, Brisbane, Berlin, and California. In this episode, we chat about content strategy, style guides, abbreviations and acronyms, developer-written UI copy, and more.