Imagine you’re a user trying to navigate a new software tool. You follow the carefully crafted documentation, only to find that it’s hopelessly out of date. Buttons have moved, workflows have changed, and suddenly you’re knee-deep in frustration, wondering if you’re doing something wrong.
This isn’t just annoying — it’s a major drain on productivity and a source of endless headaches for both users and the development teams supporting them.
Tests and Docs
Most web applications I’ve seen suffer from two problems that I didn’t know were interconnected until recently.
- As a developer, end-to-end tests are cryptic, brittle, and hard to debug when they fail.
- As a user, documentation is perpetually out of sync with the actual product.
When tests break, developers are left scratching their heads, trying to decipher where the expected behavior diverges from reality. And when docs are outdated, users are essentially being misled about how the software actually works.
The Real Cost
The impact of this documentation decay goes far beyond mere inconvenience:
- User Frustration: Nothing erodes trust faster than documentation that doesn’t match the product.
- Support Overload: Inaccurate docs lead to an influx of avoidable support tickets.
- Reduced Adoption: Users may abandon the product if they can’t figure out how to use it correctly.
- Brand Damage: Inconsistent documentation reflects poorly on the overall quality of the product.
Breaking the Cycle
The root of the problem is clear: keeping user documentation in sync with a rapidly evolving product is a Herculean task. Manual updates are tedious, error-prone, and often the first thing to be neglected when deadlines loom.
Write documentation and tests together
What if there was a way to make your documentation an integral part of your testing process? A method to ensure that every UI change, every workflow tweak, was automatically reflected in your user-facing guides?
My solution lies in writing your end-to-end tests and user documentation together. Here’s how this approach works:
- You write your documentation in a format that can also serve as a test script.
- These documentation files are then executed as actual tests against your web service.
- During the test run, the process captures screenshots and generates an up-to-date documentation website.
This unified approach ensures that your documentation is always in sync with your web service. If a test fails, it means your docs need updating—and you’ll know exactly where and how. It’s a game-changer for maintaining accuracy and user trust.
Bringing the Idea to Life
In order to implement this approach, I’ve developed a small tool that automates this process. It allows developers to write executable documentation in markdown that serves both as end-to-end tests and as the basis for user-facing guides. The tool automates the process of running these tests and generating a polished documentation website.
If you want to try it out too, I published it on Github: https://github.com/lovasoa/docurun
