Testified Documentation
Hello HN, I'd like to share an idea and a library that implements it. As a fan of "Specification by Example" (as described in Gojko Adzic's renowned book), I faced numerous challenges trying to introduce these ideas at work or in hobby projects. Surprisingly, the most challenging part was writing specifications and examples in Gherkin/Cucumber syntax and producing readable living documentation out of them. I believe that the Given... When... Then... format is not the best for user-facing documentation. Personally, I find novel-like narratives, filled with code examples, design…
What it does
In the maker’s words, at launch
Hello HN, I'd like to share an idea and a library that implements it. As a fan of "Specification by Example" (as described in Gojko Adzic's renowned book), I faced numerous challenges trying to introduce these ideas at work or in hobby projects. Surprisingly, the most challenging part was writing specifications and examples in Gherkin/Cucumber syntax and producing readable living documentation out of them. I believe that the Given... When... Then... format is not the best for user-facing documentation. Personally, I find novel-like narratives, filled with code examples, design decisions, and diagrams, much more appealing. The question was: how can we ensure that the documentation reflects the current state of the system? That is how the "Testified Documentation" was born. What if we combine something already present and widely adopted by developers - automated tests and documentation generators? In a nutshell: 1. We start the implementation once the business/community need is clear and there is a shared understanding. 2. We briefly document the new feature and reference (so far non-existing) tests. 3. We write the tests. 4. We implement the feature. 5. We repeat steps 2-4 until the feature is fully implemented and documented. 6. We have an up-to-date document that explains how the system works. This might also be appealing to open-source projects, which we document anyway. We can ensure that documentation is up-to-date by testifying it! And finally: sphinx-testify is a very simple extension to the Sphinx documentation generator that enables the ideas described above. I would appreciate your opinion, criticism, and thoughts!
Does the same job
all alternatives →
- IMI made a free documentation tool2021 · sidepage.co · ▲77
- TDThe declarative way of documenting components2020 · pitsby.com · ▲10
- VRVarious README templates and tips on writing high-quality documentation2019 · github.com · ▲24
More dev tools this month
the category →
Open-source GTM skills for technical founders
Dev tools · 29d ago · gtmcofounder.com
OpenTrailPaper is open-source bike computer firmware for the LilyGO T5S3 4.7" E-Paper PRO. It supports offline maps, GPX routes, FIT recording and Bluetooth sensors.
Dev tools · 1d ago · opentrailpaper.com
Launched alongside, January 2025
the whole month →- IM
Hello! I'm Byran. I spent the past ~6 months engineering a laptop from scratch. It's fully open-source on GH at: https://github.com/Hello9999901/laptop
Dev tools · 2025 · byran.ee
- TITetris in a PDF▲1,289
I realized that the PDF engines of modern desktop browsers (PDFium and PDF.js) support JavaScript with enough I/O primitives to make a basic game like Tetris. It was a bit tricky to find a union of features that work in both engines, but in the end it turns out that showing/hiding annotation "fields" works well to make monochrome pixels, and keyboard input can be achieved by typing in a text input box. All in all it's quite janky but a nice reminder of how general purpose PDF scripting can be. The linked PDF is all ASCII so you can just open it in a text editor, or have a look at…
Life & fun · 2025 · th0mas.nl
Create lifelike, personalized AI avatars from text prompts
AI · 2025 · jogg.ai
