logo
episode-header-image
Yesterday
1h 3m

Docs as Tests: Keeping documentation res...

Kate Mueller
About this episode

In this episode, I'm talking with Manny Silva, a technical writer who created the "Docs as Tests" concept name and the open-source tool Doc Detective. We discuss how to automatically test your documentation for accuracy, why customer reports of broken docs are actually failed tests, and practical ways to implement automated documentation testing regardless of your tech stack.

Manny and I discuss his background as someone who intentionally chose technical writing as a career path, starting with early exposure to computers through his mother's work and developing into roles at Apple, Google, and now Skyflow as Head of Documentation. We explore the core concept behind Docs as Tests—that documentation contains testable assertions about how a product should work, and that customer reports of broken procedures are essentially failed tests that we should catch proactively rather than reactively.

We dive deep into how Manny's strategy works in practice, from the "cupcake to wedding cake" approach of starting small and scaling up. We dig into two different approaches to the technical implementation: creating “detected” tests using Doc Detective, which reads the docs directly and uses them as tests, and creating standalone tests in testing tools like Playwright or Cypress, which you’d create and update independently of the docs. Manny explains how his Doc Detective tool can parse markdown documentation, automatically execute the steps described in procedures, capture screenshots for visual regression testing, and even validate API responses against OpenAPI schemas. We discuss the business case for automated documentation testing, including how it prevents customer frustration, builds trust, reduces support overhead, and can catch bugs before they reach production.

Throughout our conversation, we explore practical implementation strategies, including how to sell the approach to stakeholders, integrate testing into CI/CD pipelines, handle multifactor authentication challenges, and work with QA teams. Manny also shares his philosophy of creating a "zero trust" relationship between docs and product—not out of disrespect, but to ensure everyone stays honest about the behavioral contract that documentation represents. Docs as Tests also encourages technical writers to embrace their unofficial QA role–as writers, we’re often the first to test a new feature or product, and embracing a Docs as Tests mindset can help legitimize and make visible this role.

About Manny Silva:

Technical writer by day, engineer by night, and father everywhere in between, Manny wears many (figurative) hats. He's passionate about intuitive and scalable developer experiences, and he likes diving into the deep end as the 0th user.


Here are a few things that keep him busy:

  • Head of Docs at Skyflow, a data privacy vault company.
  • Codifier of Docs as Tests, a tool-agnostic strategy for keeping docs and their products in sync by using doc content as product tests.
  • Creator and maintainer of Doc Detective, an open-source doc testing framework.
  • AI development and experimentation.

He's always looking for collaborators on projects, and he loves chatting with folks, so don't hesitate to reach out.


Resources discussed in this episode:




Contact The Not-Boring Tech Writer team:


We love hearing your ideas for episode topics, guests, or general feedback:

Join the discussion by replying on Bluesky


Contact Kate Mueller:

Contact Manny Silva:

Contact KnowledgeOwl:

Up next
Jun 26
Connecting permaculture and documentation with Liz Argall
In this episode, I’m talking with Liz Argall, a writer I connected with at Write the Docs Portland 2025. We talk about working on open source projects, developing good qualitative metrics, her work with a permaculture nonprofit in Uganda, and the ways that being interviewed by a ... Show More
45m 52s
Jun 12
Documentation as a creative endeavor with Nick Graziade
In this episode, I'm talking with Nick Graziade, a technical writer and musician who approaches documentation as a creative endeavor. We explore how his early fascination with Lego instructions and synthesizer manuals shaped his philosophy that technical writing doesn't have to b ... Show More
50m 17s
May 29
Kate sounds off on Write the Docs
In this solo episode, Kate shares an update on her content update progress. She also reflects on Sue Brandt’s interview (S3:E10) and on the Write the Docs Portland 2025 conference.I’ve continued my work to update the KnowledgeOwl Support Knowledge Base to align with major navigat ... Show More
26m 51s
Recommended Episodes
Jul 2024
Tracking technology stacks, practices and experiences across teams
Understanding your technology estate and how it's being leveraged is critical for organizations; it impacts everything from financial planning to capability development. But given the rapid pace of change — even inside a single organization, let alone the wider industry — how can ... Show More
36m 59s
Dec 2024
124. From Ideas to Impact: Chris Strahl and Evan Lovely on Five Years of Design Systems Innovation
Send us feedback or episode suggestions.In this special episode of the Design Systems Podcast, co-founders Chris Strahl and Evan Lovely celebrate five years of the podcast and reflect on their journey from agency work to building Knapsack. They discuss the evolution of design sys ... Show More
34m 2s
May 2024
GSK’s Use of AI in Vaccine Tech, Drug Discovery
GSK’s Chief Digital and Technology Officer Shobie Ramakrishnan discusses how the company is leveraging AI and data models for vaccine development and drug discovery in this episode of Bloomberg Intelligence’s Tech Disruptors podcast. BI’s Health-Care Analyst Sam Fazeli and Techno ... Show More
42m 42s
Feb 2025
Tool calling and agents
It seems like everyone is uses the term “agent” differently these days. In this episode, Chris and Daniel dig into the details of tool calling and its connection to agents. They help clarify how LLMs can “talk to” and “interact with” other systems like databases, APIs, web apps, ... Show More
45 m
Aug 2024
GemFire with Ivan Novick
Tanzu GemFire is a distributed, in-memory, key-value store that performs read and write operations at fast speeds. It offers highly available parallel message queues, continuous availability, and a scalable event-driven architecture. It was developed to have sub-millisecond respo ... Show More
34m 12s
Oct 2022
AI Today Podcast: Applying CPMAI in the Real World, Interview with Andrew Stone, Maximus
It’s one thing for us to talk about the Cognitive Project Management for AI (CPMAI) Methodology and the benefits it can bring to managers running AI and advanced data projects, but hearing directly how individuals are applying the CPMAI Methodology can be incredibly valuable. In ... Show More
47m 26s
Nov 2024
476. Navigating the Murky Waters of Data Rights with Brad Templeton
From medicine to technology, our world is run by science. In this episode of the Marketing Speak podcast, join our dive into technology and its impact as we sit down with Brad Templeton to unravel the intricacies of our tech-driven world. Brad is the founding faculty for Computin ... Show More
34m 57s
Jul 2024
Professional Scrum Powers Strobbo's Go-to-Market Acceleration (Part 1)
Strobbo, an HR platform faced challenges with its software development processes. The company’s initial mechanical approach to Scrum, coupled with poor communication and lack of trust, hindered progress and morale. To address these issues, Co-Founder Bert Neels brought in Profess ... Show More
35m 54s