A technical writing podcast about the latest trends and practices in the field of technical communication. Technical communication includes topics like technical writing (software help), information architecture, usability, API documentation, information design, web design, illustration, DITA, structured authoring, visual communication, and more. If youre a technical writer or interested in technical writing, this is the one of few podcasts in this niche. I also have a blog at http://idratherbewriting.com where the podcasts and other blog topics are published.
Recording of Let's Tell a Story -- Scenario-Based Documentation, by Matt Ness (STC Silicon Valley Presentation)02/09/2016 Duración: 55min
Matt Ness, a technical writer at Splunk and a co-organizer for WTD San Francisco, recently gave a presentation to the STC Silicon Valley chapter called Let's Tell a Story: Scenario-Based Documentation. In this presentation, Matt talks about ways to integrate storytelling techniques into documentation, drawing upon his experience as a Dungeons and Dragons player and his player experience from other video game or fantasy worlds. To help users on their journeys and quests, you need a narrative to guide them and a manual to help them overcome obstacles. Video, slides, and audio from the presentation are included in this post.
The complexities of translation and the need for dynamic variables in the build process15/08/2016 Duración: 14min
Translation is a complex undertaking that usually requires you to take advantage of dynamic variables and other parameters in your source format in order to generate out different languages. Although most people think of static site generators as containing static content only, it's actually only static output. During the build process, you can take advantage of these more dynamic characteristics to handle rules for outputting to different languages. In this post, I explain some of the details you have to account for (includes, links, images, re-used content, etc.) when managing a translation project using a static site generator such as Jekyll.
Presentation recording: Hunting for API developer documentation jobs in the San Francisco Bay area, by Andrew Davis15/08/2016 Duración: 01h13min
Andrew Davis recently gave a presentation on finding developer documentation jobs (mostly for API documentation) in the San Francisco Bay area. The title of the presentation is Hunting for Dev Doc Work around the Bay. You can listen to the presentation recording, check out the slides, or just download the audio.
The Story of Paligo: A new browser-based CCMS with all the features you'd ever want01/08/2016 Duración: 08min
Up until two years ago, Anders Svensson and his colleagues, based in Sweden, provided DITA and XML consulting. They eventually created their own XML-based component content management system (CCMS) called Paligo, which includes a full set of documentation features to handle single-sourcing, translation, and other documentation needs. Paligo solves the challenges that Svensson's customers had been facing for years with other CCMS systems.
Will the docs-as-code approach scale? Responding to comments on my Review of Modern Technical Writing01/08/2016 Duración: 16min
My previous post reviewing Andrew Etter's ebook on Modern Technical Writing got an enormous response. Some readers said the docs-as-code approach works only for small shops and doesn't scale to large projects. They said content re-use and translation also become problematic. However, perhaps the real differentiator shouldn't be product size as much as product category. The docs-as-code approach (which is what I'm calling it) works particularly well for developer documentation, such as API documentation, which usually doesn't contain the same challenges that component content management systems (or CCMSs) were meant to solve.
Review of Andrew Etter's ebook on Modern Technical Writing26/07/2016 Duración: 10min
In Modern Technical Writing: An Introduction to Software Documentation, which is an e-book you can read on your Kindle, Andrew Etter argues for a model of technical writing that involves lightweight markup languages (like AsciiDoc and Markdown), static site generators (such as Sphinx), distributed version control systems (like Git or Bitbucket), constantly iterating/updating doc content on your website based on analytics, and more. Etter's book resonated with me because it articulates so many of the principles I've felt about how documentation should be.
Applying Tim Ferriss' 4-hour work week rules to tech comm projects20/07/2016 Duración: 09min
Principles in Tim Ferriss' book The 4-Hour Work Week can be applied to tech comm projects. By focusing on the 20% of tasks that result in 80% of the results, limiting your focus to two mission critical tasks a day, empowering those around you to make decisions, and avoiding distractions from trivial tasks, meetings, and email, you can be much more productive in your work. More than crossing off a list of tasks, this approach will likely make your efforts matter.
Thoughts on Transforming Documentation Processes presentation at WTD: Evaluating the trend to treat documentation as code15/07/2016 Duración: 09min
At the last Write the Docs conference, Riona Macnamara, a tech writer working on internal developer documentation at Google, moderated a panel about transforming your documentation process. The panel consisted of four writers from various companies -- Balsamiq, Rackspace, Microsoft, and Twitter. The panelists talked about how they increased collaboration and openness in their company's doc culture by transforming their authoring and publishing processes. Most of these transformations involved adopting a 'docs as code' type approach, which seems to be a growing trend.
Context switching and efficiency -- Kanban to the rescue?13/07/2016 Duración: 07min
In Become More Productive and Motivated, Mattias Sander provides a well-written overview of Lean, which is a strategy for eliminating waste and focusing more on customer value. What interests me most with Sander's discussion about Lean is context-switching and the subsequent strategy of Kanban, which uses cards to regulate flow. While these principles were developed in the context of Japanese car manufacturers (namely Toyota), they apply equally to the technical writer's world.
Why Programming Sucks and the fallacy of documentation in the context of code chaos12/07/2016 Duración: 07min
Yesterday on Write the Docs, someone shared an article titled Programming Sucks, by Peter Welch. More than just a developer monologue, this article seems to hit on universal truths about programming, so much so that the article has been translated into 10 languages and even has a professionally-read audio version on iTunes (which I bought for $2).
Thoughts on Documentation Avoidance for Programmers09/07/2016 Duración: 06min
This past week on the Write the Docs forum, there was a bit of discussion around a recent presentation titled Documentation Avoidance for Programmers. In the presentation, Peter Hilton lays out a series of tips on how programmers might get out of writing documentation.
Presentation recording: Move Fast And ... Document Things? Lessons learned in building documentation culture at a startup, by Ruthie Bendor22/05/2016 Duración: 35min
During the May WTD meetup, Ruthie Bendor, a web engineer, gave a presentation titled Move Fast And ... Document Things? Lessons learned in building documentation culture at a startup. This post contains the audio and video recording of her presentation.
Recording of Version Control, Writers, and Worfklows by Richard Mateosian17/12/2015 Duración: 01h03min
You can watch the recording of Richard Mateosian's November 2015 presentation to the STC Silicon Valley about version control, writers, and workflows.
Podcast: Spec-driven Development of REST APIs, with a focus on RAML -- interview with Michael Stowe12/10/2015 Duración: 45min
Spec-driven development is an approach to developing REST APIs by first describing and prototyping the API through a specification file (such as RAML or Swagger), and then coding the API. The spec not only serves as a contract for the API's development, it can also generate interaction documentation, unit tests, client SDKs, and provide other benefits.
Udemy podcast (with me) and infographic on technical writing06/10/2015 Duración: 38min
Recently I was interviewed by Alex Bankoff from Udemy for a podcast on the field of technical writing. The Udemy team also created an infographic about the topics covered in the podcast.
Podcast: The divide between academics and practitioners -- Interview with Lisa Meloncon10/08/2015 Duración: 57min
In this podcast, I talk with Lisa Meloncon, an associate professor at the University of Cincinnatti, about the academic-practitioner divide.
Podcast: How do design, length, and relevance affect how people use API reference docs -- interview with Bob Watson30/07/2015 Duración: 52min
Bob Watson recently finished a PhD with research that examined how the design and content of API reference docs affects the user's performance. In this podcast, I talk with Bob about his findings and his other research interests, primarily around goal testing to measure documentation's effectiveness.
The key to writing good documentation: Testing your instructions07/07/2015 Duración: 23min
Writing good documentation requires you to set up a test environment and test all of your instructions -- testing the instructions yourself and against a user. Testing instructions can be time consuming and tricky, especially with developer documentation. It's hard to see past personal blind spots and assumptions. But testing instructions gives you access to insight that makes your documentation much more accurate and useful.
API Documentation presentation to East Bay STC chapter -- slides and recording16/05/2015 Duración: 01h50s
The other week I gave a introductory presentation on API documentation to the East Bay STC chapter in Silicon Valley. Here are the slides and recording.