Search results

Write the Docs Podcast episode 1: New podcast from the Write the Docs community

by Tom Johnson on Nov 23, 2016
categories: technical-writing wtd-podcasts

The Write the Docs community now has a podcast available. The podcast follows a discussion-based format with several co-hosts talking about recent articles or topics related to tech comm. The podcast is available on almost every podcast platform.

Write the Docs Podcast details

You can view the new Write the Docs podcast here: podcast.writethedocs.org. I’m one of the co-hosts, along with Jared Morgan, Carlee Potter, and Chris Ward. Jared and Carlee are based in Australia, and Chris is in Berlin (though he’s English/Australian).

Here’s the first episode:

How the podcast started

I felt there was a need for a discussion-based podcast similar to Leo Laporte’s This Week in Tech (TWIT), so I asked around on the Write the Docs #podcast Slack channel channel if others were interested. Jared, Carlee, and Chris all wanted to do a podcast too.

Although we’ll be the core co-hosts, we’re also planning to rotate in other WTD community members as well. Right now the podcast is in its early stages, and we have just one episode recorded.

The podcast is a group effort, with everyone pitching in, from the recording to the post-editing to the website and more.

Building the podcast site

I helped build the site, so I want to mention a few details here. To build the site, we started with this Soundcast HTML theme. I then converted it to Jekyll. The conversion to Jekyll is surprisingly simple. At some point I want to write a more detailed guide on how to convert a site to Jekyll, but basically converting an HTML site to Jekyll involves the following:

  • Add a _config.yml file to the project.
  • Define a layout in the _layouts folder.
  • Insert the {{content}} tag into the layout where you want page content to appear.
  • Add front matter tags into your pages, with the layout specified.
  • Use for loops to iterate through lists of content.

The most difficult part was modifying the HTML from the original theme to exclude all the layouts that we didn’t need or want.

The heart of any podcast site is the media RSS feed. You can see this feed at http://podcast.writethedocs.org/itunes.rss. The RSS feed is how you syndicate your site across different channels, such as iTunes and Stitcher.

The template for the media RSS feed is here. In some places, the template gets values stored in the _config.yml file.

The template also loops through the latest posts that have podcasts as a category and inserts values from the frontmatter in those posts into the RSS feed automatically. You can see the frontmatter for the post here.

Subscribe to the Podcast

Enough of the technical details. I encourage you to subscribe in some form or another – whether iTunes, Stitcher, Pocketcast, Youtube, RSS, Email, or some other method. We hope to publish regular podcasts here, with at least a monthly cadence, if not more frequently.

Let us know if you have any topic requests or feedback.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.