Introduction

Welcome to Docs as Tests: the novel concept of automating documentation testing so that content stays up-to-date, always keeping pace regardless of product changes.

Documentation is the backbone of user experience, serving as the bridge between complex technologies and their users. Docs guide, educate, and support users through their journey with a product or service.

However, maintaining accurate docs in the face of rapid product change is the bane of many writers’ lives—and a challenge that’s often poorly addressed. It’s a challenge that can cost organizations time, money, and users if handled badly.

This book introduces a novel approach: treating docs as tests to actively verify content against the current state of the product—rather than finding consistency issues too late through frustrated customers, faltering sales, and increased support calls.

I’ve written this book for technical writers, documentation specialists, and anyone else involved in the creation and maintenance of documentation, even if you don’t have “writer” in your title. It doesn’t matter if you’re working in a small startup or a large enterprise: the principles and practices outlined here are universal.

What Does That Mean?
Technical Writing: Communicating complex information in understandable terms, often through documentation.

“But how will I put this new concept into practice?” I hear you cry. “Are the tools I need even within reach of the average technical writer?”

Previously, no. But that’s changed. With new technologies available, content creators are more empowered than ever to have testable, verifiable documentation and ongoing confidence that their docs are accurate—no matter how frequently their products change.

And it doesn’t matter what format or system houses your content—Docs as Tests works with any documentation source. Whether you use a CCMS, CMS, Docs as Code workflow, Word document, or any other content solution, the principles remain the same. The only limitations come from the specific testing tools you choose, not from the strategy itself. Docs as Tests is about validating content against your product, regardless of how that content is authored or stored.

Turn the page. Let’s get started.

Who this Book is For

Regardless whether you’re just starting out in the field, you’re grappling with the nuances of technical communication, or you’re a seasoned professional seeking innovative approaches to improve documentation quality, this book has something for you. This book caters to

• Technical writers at any stage of their career seeking to keep their documentation accurate despite product changes.
• Software developers and engineers who contribute to docs and are looking for efficient ways to validate the accuracy of their docs against the product.
• Product managers who understand how docs impact product adoption and who want to integrate automated testing into their docs workflows.
• Documentation managers and team leads looking for scalable, automated solutions to maintain the freshness of their docs without manual overhead.
• Technical communications academics who want to incorporate modern, practical tools and methodologies into their curriculum, preparing students for the realities of tech writing in the industry.
• Quality assurance professionals interested in extending their testing frameworks to cover documentation, ensuring that the doc accurately reflects the product at all times.
• Consultants seeking a robust, process-oriented approach to documentation testing that can be adapted and applied across various client projects.
• Technical marketers who want certainty that their best performing content isn’t going stale because of product updates.
• Support managers who want to know that their internal processes aren’t about to break.

If any of the above describes you, you’ve chosen the right book.

About the Author

Manny Silva

Manny has fifteen years of experience in technical communication, including creating documentation for Apple, Google, and Skyflow. He codified the Docs as Tests strategy and created Doc Detective, a tool for implementing Docs as Tests. He’s passionate about intuitive and scalable developer experiences, and he likes diving into the deep end as the 0th user.

How to Use this Book

This book is structured in two parts: “What and Why” discusses the history and theory of applying testing to documentation, while “How” details strategies for testing different product surface areas: Graphical User Interfaces or GUIs (see Chapter 5: Testing GUI Docs), Application Programming Interfaces or APIs (see Chapter 6: Testing API Docs), Command Line Interfaces or CLIs, and Software Development Kits or SDKs (see Chapter 7: Testing Code in Docs and Docs in Code).

Each chapter has an introductory narrative in italics so you can follow Vincent, a fictitious tech writer, through his Docs as Tests journey as you continue through the book.

You don’t have to follow every step or read every page. The bitesize format of this book allows you to take it at your own pace, skipping anything that isn’t relevant to you.

What Does That Mean?

GUI (Graphical User Interface): The visual way users interact with software through elements like buttons, menus, and windows. API (Application Programming Interface): A set of rules and tools that allows different software applications to communicate with each other. CLI (Command Line Interface): A text-based way to interact with software by typing commands. SDK (Software Development Kit): A collection of tools, code samples, and documentation that help developers build software that works with a specific platform or programming language.

Symbols Used in this Book

While reading this book, you’ll encounter reader aids, which are easily identifiable by their accompanying symbols. The following table describes the purpose of each symbol.

Table 2: Symbols Used in this Book

	Insight: Insights offer an extra dimension to the guidance provided in this book. They may suggest career-enhancing moves, sound notes of caution, or shed additional light on a concept.
	What Does That Mean? Definitions for technical jargon used in the accompanying text. All definitions are compiled in the glossary.
	Note: Additional information about a concept or section that is not essential for understanding but provides more context.
	Voice of Practitioner: Anecdotes from individuals I interviewed during the creation of this book.

Acknowledgements

Thank you to everyone who listened and encouraged me on this journey of discovery.

Thank you Amruta Moktali for encouraging me and empowering me to pursue my wild ideas.

Thank you Ana Fajnor for helping me clarify my thoughts into the following concepts and prose.

Special thanks to Ashley Gordon, Niko Barry, Anne Gentle, Nate Waddington, Sean Falconer, and Courtney Roberson for acting as my expert reviewers and for continually challenging me.

And most of all, thank you Vanessa for trusting that my crazy project would be meaningful in the end and helping me find that meaning. I love you more than I can ever express.

“Trust is consistency over time. There’s no shortcut for either.”

-Jeff Weiner, former CEO of LinkedIn