Show HN: Testified Documentation

6 points · basicwolf · 5 days ago

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!