3 ms·
I started doing documentation driven development a while back (with FOSS code) I wrote and I realized at some point that my tests and my how to docs were doing
by hitchstory 3y ago
I started doing documentation driven development a while back (with FOSS code) I wrote and I realized at some point that my tests and my how to docs were doing the same thing - one was just an easier to read version of the other.
Moreover, when one went out of date so did the other.
So, I tied them together - I wrote integration tests such that with a jinja2 template I could autogenerate readable markdown how-to docs from the tests and their artefacts.
Setting that up led me to the realization that writing docs isn't actually tedious at all. It's the writing things down 3 times (spec, test & docs) and keeping them in sync that is tedious. And that part can be automated.
If there is a framework to build the whole bundle of docs from integration tests, integration test metadata, integration test artefacts, schemas, code and an assortment of high level explanatory texts then it stops being a chore. It actually becomes fun.
It means that DDD becomes integration TDD. The only difference is that I will write an additional 3-4 explanatory sentences alongside the integration test I write before the feature and run a "docgen" script afterwards.
- rapnie 3y agoWhat are your thoughts on BDD and Gherkin test scripts? The federated Diaspora* app has a BDD test suite [0], and for the Fediverse people are test-driving if it is applicable for ActivityPub compliance testing [1]. [0] https://github.com/diaspora/diaspora/tree/develop/features https://github.com/diaspora/diaspora/tree/develop/features [1] https://codeberg.org/helge/fediverse-features https://codeberg.org/helge/fediverse-features
- hitchstory 3y agoI don't like gherkin. I think that it has awkward syntax, it lacks type safety, it's very verbose and doesn't have enough ability to abstract scenarios. Rather than being a source for generating the documentation it tries to be the documentation. Nonetheless, there is a small number of projects where they either work around these constraints or it doesn't matter as much, so it can work. I find that most people that apply gherkin to their projects run into a brick wall though - usually for one of the above reasons. I built https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity and the ability to abstract scenarios. It is explicitly designed as a source for generating markdown documentation so that you can create richer docs like https://github.com/hitchdev/hitchstory/blob/master/examples/website/docs/correct-my-spelling.md https://github.com/hitchdev/hitchstory/blob/master/examples/... for your users rather than more test-like documents like https://github.com/diaspora/diaspora/blob/develop/features/mobile/change_password.feature https://github.com/diaspora/diaspora/blob/develop/features/m...
- rapnie 3y agoNice. I like the approach, thank you.