Documentation Engineering: Test Data Workbench
Most projects treat documentation as the thing you write after the code. I built this one’s docs as engineering: a Sphinx site that fails its own CI build on a single broken cross-reference, held to the same pass-or-fail bar as the test suite.
Overview
This entry is about the documentation, not the tool it documents. The distinction is the point: making a complex system legible is a separate skill from building it, and developer-experience, technical-writing, and developer-education work is hired on it directly.
The Test Data Workbench documentation is a full site built with the same rigor as the code it explains: versioned, reviewed, and CI-gated. It is organized around what a reader needs (Getting Started, Concepts, Foundations, Technology Stack, Reference) rather than around how the code happens to be laid out, and it is honest about the tool’s limits instead of papering over them. The live site is at volanticsystems.github.io/test-data-workbench, and a purpose-built page, “How these docs are built,” states the approach directly.
Technical
The site is Sphinx with the Furo theme, built from source and deployed by GitHub Actions on every push. Three practices make it a system rather than a pile of prose:
- Warnings are errors. The build runs under
-W, so a broken cross-reference, a malformed heading, or a link to a page that no longer exists fails the build outright. The docs pass or fail like tests; they cannot rot quietly. - The reference is generated from source. Sphinx autodoc reads the actual classes, signatures, and docstrings out of the installed package rather than restating them by hand, which removes the usual drift between code and its documentation.
- Content is grounded in the real code. Technology chapters are written against specific modules and show how each library is actually used and why it was chosen, not abstract tutorials. Concept chapters cover design principles, architecture, schema-adaptation, and privacy, and a lineage chapter traces three generations of the project.
Why You Should Care
Documentation is where most engineering projects quietly give up, and a reader can tell within a screen whether the docs were a deliverable or an afterthought. Holding a documentation site to a failing-CI bar, generating its reference from source so it cannot drift, and structuring it around reader needs is documentation engineering: the discipline that goes into building a system, applied to explaining it.
The subject here happens to be the Test Data Workbench, but the competency on display transfers to any complex system that has to be made legible, learnable, and maintainable. That is a developer-experience and technical-communication problem, and it is one plenty of otherwise-strong engineering organizations have never solved.
Status
Live and CI-deployed alongside the tool it documents. It shares a repository with the Test Data Workbench product entry; the two are kept separate because they demonstrate different skills to different buyers. Per the project’s own principle, the docs live attached to a real, working, published tool rather than in a repository of their own.
Docs: https://volanticsystems.github.io/test-data-workbench/ How these docs are built: https://volanticsystems.github.io/test-data-workbench/documentation-engineering.html