Write the Docs Podcast Write the Docs Podcast

In this podcast, we discuss the newly released book with Jared Bhatti, staff technical writer at Google, and Zachary Sarah Corleissen, staff technical writer at Stripe (two of the co-authors). This book on writing documentation focuses on the end-to-end writing process (from audience analysis to drafting, editing, publishing, and more) and is written specifically with developers in mind. The authors use the scenario of documenting Corg.ly, an API that translates barks, as a common thread through each of the chapters.

In this podcast, Fabrizio Ferri joins us for a discussion about adding both personal identity and personality to documentation. Why are the docs we write so often anonymous, and does that anonymity work against progress in our careers? Are tech writers, who are typically introverts, averse to publicity, or does our industry not allow for it? And if you want to be a "personality" in the tech communications world, what do you do? How do you add personality constructively to your work without disrupting corporate brand and consistency?

One of the most challenging and frustrating things about being a tech writer is managing screenshots in your product documentation. How many times have you needed to take complex screenshots of your product and meticulously marked them up with callouts only to be told that a field has changed and you need to do everything again? It’s so frustrating and demoralizing as a writer because it feels like wasted effort. What if there was a way to create screenshots that could withstand the rapid iterations of a product under development while still conveying valuable meaning to your readers. Today we’re joined by Anton Bollen from TechSmith who explains how we can do this using low-detail screenshots, aka simplified user interfaces, that let you focus your users' attention on just the bits of the interface that matter.

Many tech writers are familiar with using AsciiDoc for documentation, but did you know that you can also create fiction and non-fiction books with AsciiDoc, publishing to popular digital formats such as EPUB or PDF, along with HTML? In this episode of the Write the Docs podcast, we chat with Mehmed Pasic from Manning Publications about self-publishing, AsciiDoc, collaborative workflows between authors and editors, trends in book publishing, the most popular devices for consuming content, book versus video formats for technical content, and more.

So many documentation websites rely on search as part of their information architecture. But what do you actually need to consider if you want to make your site search return answers for users in relevant, efficient ways? Join Peter Levan from Funnelback with regular guests Chris, Jared, and Tom for a talk all about making search work well on your site. Some of the questions discussed include: Why can't you just let Google do the searching and indexing for you? Do you need to pay big money to get a site search tool? How do you make your docs site talk ?

In this episode, Juan Lara from Google joins us for a lively discussion about documentation templates. Documentation templates refer to established patterns we follow for common documentation types, such as quickstarts, how-to guides, concepts, tutorials, reference, troubleshooting, release notes, FAQs, or other information types that have similar, predictable patterns. Templates can be helpful in orienting new writers, but they can also help ensure consistency among larger groups of experienced writers too. Our discussion in this episode ranges from observations about when templates are right for users versus writers, and how templates fit into an overall content strategy and information architecture. Beyond templates, your user's goals and journeys will influence the shape of your help content.