When product updates are frequent and user expectations are high, maintaining accurate and up-to-date documentation isn’t just a necessity—it’s a competitive advantage.
Docs as Tests is a strategy that keeps your docs in sync with your product. It’s a way to test your docs, just like engineers test their code. It’s a way to make sure that your docs are always accurate, complete, and relevant.
- Validate that your guides, tutorials, API references, and other docs work as written.
- Catch issues in your docs and product—before your users do.
- Reduce the time and effort required to maintain your docs.
- Build user trust by ensuring a consistent user experience between your docs and product.
- Make docs a first-class citizen in your engineering and product development processes.
By testing your doc content against your product UIs and APIs, directly navigating your websites and hitting your API endpoints, you can ensure that your docs are always accurate, complete, and relevant.
With the right tools, Docs as Tests can elevate your docs to a dynamic, living part of your product. Interested? You’re in the right place.
Recent posts
How Kong Achieved 91% AI Chatbot Accuracy Through Docs Testing
Kong’s documentation team fundamentally changed how their docs relate to their product. After rebuilding their CLI how-to guides to be testable, their AI-powered documentation chatbot accurately answered 91% of user questions with confidence, up from 84%. That 7% improvement wasn’t the result of better AI models or more sophisticated prompt engineering—it came from making sure every how-to guide on their site actually works, every time.
Docs as Tests book is Now Available!
Docs as Tests book is Now Available!
Add Docs as Tests to Your CI/CD Pipeline with GitHub Actions
August 10, 2024: Updated the tutorial to use the Doc Detective GitHub Action.
Validate README Commands with Innovation Engine
Maintaining accurate and reliable CLI-based documentation is critical, especially when it comes to installation instructions and READMEs.
Validate a UI with Cypress
Docs as Tests is a strategy for using docs to test a product, validating both that the docs are accurate and that the product is functioning as expected. That’s a great aspiration, but what does it look like in practice?
Docs as Tests: From Development to Production
The Docs as Tests methodology stems from a simple but profound principle: documentation shouldn’t just inform—it should also verify. By treating each piece of documentation as a test case that gets executed against the product, teams can preemptively identify discrepancies and ensure that what users read is what they get.
Validate Commands and Scripts with Doc Detective
We’ve covered how to validate UI procedures and API procedures with Doc Detective, but what about shell commands and scripts? After all, not every procedure is navigating through UIs or making API calls.
Docs as Tests vs. Docs as Code
Documentation has the critical role of helping users keep their footing in the storm of continuous releases driven by the iterative nature of modern product development. While many people think of documentation as creating guides and references for new features, publishing them online, and moving on to the next feature, this simply doesn’t reflect the actual challenges of technical writing in the age of continuous deployment, agile development, continuous contact, and easy access to feedback from customers. Writing is a big part of docs, of course, but maintaining those docs slides into the background as the business, product, and audience shift around them.
Validate an API with Doc Detective
Docs as Tests draws on many of the same principles as test-driven-development and data-driven-development and, as such, is a natural fit for REST API documentation.
Validate a UI with Doc Detective
Docs as Tests is a strategy for using docs to test a product, validating both that the docs are accurate and that the product is functioning as expected. That’s a great aspiration, but what does it look like in practice?