Single Source of Truth for Tests, Docs, and Demos

I've been building ERPNext customizations and open source tools for years. One pattern keeps biting me: maintaining tutorial documentation, automated tests, and demo walkthroughs separately. They drift. Someone updates the UI. The tests break. The docs become lies. Users follow outdated screenshots.

The real problem isn't the tools—it's that we're treating these as separate deliverables when they're really the same thing described three different ways.

I started thinking about this differently after dealing with Seven CMS and Seven Shop maintenance. When I change a feature, I have to touch:

• The feature itself
• The E2E tests (if I'm disciplined)
• The documentation
• The demo/onboarding flow

What if I didn't? What if I wrote the user journey once—as a concrete, step-by-step scenario—and everything else was mechanical output?

This is how I'd approach it:

Define the scenario in a structured format. Not prose. Something like: "User logs in → navigates to Products → creates new item → fills required fields → saves." Make it machine-readable but human-writable.

Then generate:

1. Test automation - Translate steps into Playwright or Cypress commands automatically
2. Interactive demo - Replay the exact same steps in a staging environment for onboarding
3. API docs - If each step maps to an API call, generate endpoint documentation
4. Release notes - Track which scenarios changed between versions

I haven't fully implemented this yet—it requires discipline to structure workflows that way. But I've seen the pain of the alternative enough times.

The catch: this only works if you're willing to be mechanical about it. You can't have prose mixed with steps. You can't let your documentation diverge into "a better explanation." Single source of truth means single.

For my open source projects moving forward, I'm experimenting with this. Start with scenarios as the artifact. Everything else follows. Less maintenance debt. Less lies in production.

If you're building SaaS or maintaining complex workflows, this pattern is worth the upfront investment.