Write the Docs Podcast

Latest Episodes:

WTD Episode 25: Researching how developers use API docs, with Andrew Head Oct 20, 2019

Show notes

In episode 25, we talk with Andrew Head, Ph.D. Candidate in Computer Science at UC Berkeley, about his research on how developers use API documentation. Specifically, we focused on a recent article he co-authored titled When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects. During the podcast, we chat about the following: where developers look for information, how developers manage information in Google’s unique billion-line code base, when it's appropriate to just let developers read the code directly versus creating documentation, what kind of information developers look for in API documentation, the relevance of document generators such as Doxygen, and more. Andrew also talked about some projects he's working on to build interactive tools for developers to share code expertise.

WTD Episode 24: Conference chatter and the Australian scene, with Swapnil Ogale Sep 22, 2019

Show notes

In this episode, we're joined by the Write the Docs Australia initiator Swapnil Ogale. We talk about conference wind-downs and ramp-ups, highlights from the just-finished WTD Prague conference, speakers announced for upcoming Write the Docs Australia conference, the Good Docs Project, the tech writing scene in Australia, and more.

WTD Episode 23: How to write inclusive tech documentation, by Lucie Le Naour Aug 19, 2019

Show notes

In this episode, rather than the usual roundtable discussion, we provide a recording of a WTD Berlin presentation by Lucie Le Naour on how to write inclusive tech documentation. Inclusive documentation takes into account all users, regardless of their gender, culture, or abilities. It uses language that treats different types of people fairly and equally, acknowledging that the words you choose matter in the connotations and attitudes they convey. This presentation was recorded on August 19, 2019 in Berlin.

WTD Episode 22: Managing multiple doc projects across Git repositories, with Giles Gaskell Jul 28, 2019

Show notes

In episode 22, Giles Gaskell from Squiz in Australia joins us to talk about managing multiple doc projects across Git repositories through Antora. Giles explains how to establish processes such that updating documentation becomes part of the definition of done, how to manage build process across multiple Gitlab repositories, strategies for distributing doc work across engineers through templates, how to scale workloads when you're the lone technical writer in the company, times when dogfooding your own product for docs makes sense and when it does not, pros and cons of Asciidoc versus Markdown, and more docs-as-code topics.

WTD Episode 21: On career growth, leadership, and mentoring in tech writing, with Becky Todd Mar 31, 2019

Show notes

In episode 21, Becky Todd from Atlassian joins us to talk about career growth, leadership, and mentoring. How do you move up to the next level at your company? Does upleveling require a management track, or there other ways to increase your leadership and influence? We also chat about mistakes we've made, what we've learned, ways to increase our influence and visibility both inside and outside corporate walls, why we sometimes back away from persuasion efforts, the balance between autonomy and micromanagement, mentoring strategies and opportunities, and other career-related topics within technical communication. We also look at the Season of Docs as an opportunity for getting involved in open source projects.

WTD Episode 20: Minimum requirements for good tech docs, with Matt Reiner Mar 02, 2019

Show notes

In episode 20, Matt Reiner from K15t joins us to talk about minimum standards for documentation - what techniques or standards can you put in place to help engineers and other contributors meet the minimum requirement for good tech docs? What essential sections, headings, or topics should you include in templates? And how do you help non-native speakers with grammar issues? We also discuss how tech writers can work with marketing to create honest and interesting writing. There seems to be the feeling that tech writing is dull but accurate and marketing copy is flashy and fluffy - we brainstorm ways technical writers can better align with marketing writers.

WTD Episode 19: Static site generators, with Jessica Parsons Jan 31, 2019

Show notes

Jessica Parsons, a documentation engineer from Netlify, joins us for Episode 19 of the WTD Podcast. Jess recently conducted a Static Site Generator workshop at the Australian Write the Docs conference at Melbourne. It was really excellent, and we've been meaning to get Jess on the show for a while to talk shop. In this episode, Jess illuminates the world of static site generators, comparing and contrasting Hugo, Jekyll, Sphinx, Gatsby, and others. Discussions focus on considerations for choosing a static site generator, and how to manage the content they consume, from APIs to Git-tracked markdown files. Headless CMS options like API-driven Strapi and Git-wrapper Netlify CMS make an appearance.

WTD Episode 18: Recap and thoughts on Write the Docs Australia 2018 Nov 25, 2018

Show notes

In episode 18 of the Write the Docs podcast, we discuss the recent Write the Docs Australia 2018 conference held in Melbourne. Jared was an emcee at the event and shares his inside perspective about what made the event so successful. We dive deep into the unconference format, how to instill the Write the Docs brand into the conference experience, how super volunteers can avoid burnout, what sessions stood out, and more. Also, Chris confesses that he has attended about 40 conferences this year, and explains a few reasons why.

WTD Episode 17: Structured writing — reasons and approaches Oct 22, 2018

Show notes

In this Write the Docs podcast episode, we chat with Mark Baker about structured writing, specifically focusing on his new book Structured Writing: Rhetoric and Process. After introducing and defining structured writing, Mark explains the four domains you can add structure: media, document, subject, and management domains. He explains the advantages of working with structure in the subject domain, and why mixing structure across subject and document domains can be inefficient. We also chat about how structured writing connects with SEO and microformats on the semantic web, the limits of structure in Markdown formats, how to implement structure in linking, and more.

WTD Episode 16: An open-source Grammarly for tech docs? Sep 05, 2018

Show notes

This episode focuses mainly on testing tools. Last month, some rockstar WTD community members spent a few days at the Pronovix offices in Szeged, Hungary, trying to create a series of open-source testing tools. Specifically, they wanted to create a ‘create a container deployable solution that can automatically check docs’. In more blunt terms, a kind of open-source Grammarly, but integrated into deploys and repositories and focused on tech docs. Host Chris Ward and our podcast guest Anett Pozsar from Szeged (pron. Seg-jed) Hungary also participated in the Test-the-Docs hackathon. Anett recently started in her role as a technical writer, so in this episode we also chat about what it's like starting out as a new technical writer. Finally, we transition from testing tools and linters to templates. Structure and templates can be especially helpful for guiding engineers in writing docs.

Our TOPPODCAST Picks

Follow Us

Stay Connected

Related Podcasts

Links

Stay Connected