hitchstory VS livebook

I built something like this too:

https://github.com/hitchdev/hitchstory/blob/master/examples%...

I took the same approach to "docs are tests and tests are docs" with integration testing when I created this library: https://github.com/hitchdev/hitchstory

I realized at some point that a test and a how-to guide can and should actually be the same thing - not just for doctests, but for every kind of test.

It's not only 2x quicker to combine writing a test with writing docs, the test part and the docs part reinforce each other:

* Tests are more easily understandable when you attach written context intended for human consumption.

* Docs are better if they come attached to a guarantee that they're valid, not out of date and not missing crucial details.

* TDD is better if how-to docs are created as a side effect.

I have created a project for easily writing this type of test with YAML:

https://github.com/hitchdev/hitchstory

I dont think that this type of task is really appropriate for an LLM though. It is better to use hard abstractions for the truly deterministic stuff and for other stuff where you may need to do subtle trade offs (e.g. choosing a selector for the search bar) an LLM will generally do a bad job.

For those interested in the concept of having permanently up-to-date documentation with screenshots I built this testing framework based upon the idea that good documentation can be a autogenerated artefact of good tests:

https://github.com/hitchdev/hitchstory

I don't like gherkin. It's it has very awkward syntax, it's not type safe, it's very verbose, it has no ability to abstract scenarios and 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 this or it doesn't matter as much. I find that most people that apply gherkin to their projects find it doesn't work - usually for one of the above reasons.

I built https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity, and is explicitly designed as a source for generating documentation rather than trying to be the documentation.

I built this because I had the same idea: https://github.com/hitchdev/hitchstory

If the specification can be tested and used to generate docs and can be rewritten based upon program output then the maintenance cost for producing docs like these plunges.

-c fsync=off -c synchronous_commit=off -c full_page_writes=off

I got the answer from Karen Jex at Djangocon 2023.

I used it to build some integration tests which exhibit best practices: https://github.com/hitchdev/hitchstory/tree/master/examples/...

I considered using tmpfs but I wanted to cache the entire database volume and couldnt figure out how to do that with podman.

This is incredible work.

To anyone curious, I highly recommend:

- https://hitchdev.com/hitchstory/approach/

- https://hitchdev.com/hitchstory/why-not/

From the overall RDD/BDD type home page:

- https://hitchdev.com/hitchstory/

The entire product site is a thing of richly informative beauty.

---

My only question was whether the generated 'docs' snippets would add value over just reading the story in your DASL. Any markdown site generator (such as the chosen Material for MKDocs) can just embed the ```yaml anyway. But then I realized what was generating e.g. …

- https://hitchdev.com/hitchstory/using/engine/rewrite-story/

… and how superior that is to typical docs, especially typical docstring or swagger factories.

To get started you need a running instance of Livebook

LiveBook site

I prefer functional programming with Livebook[1] for this type of thing. Once you run a cell, it can be published right into a web component as well.

[1] - https://livebook.dev

If you're a coder, Livebook might be worth a look too. I certainly have my eyes on it.

Would highly recommend looking at Jose's use of livebook to answer these. It makes testing easier. It's old but still relevant. Video link inside

That's hard to say. Racket is a rather complete language, as is F# and Elixir. And F# and Racket are extremely capable multi-paradigm languages, supporting basically any paradigm. Elixir is a bit more restricted in terms of its paradigms, but that's a feature oftentimes, and it also makes up for it with its process framework and deep VM support from the BEAM.

I would say that the key difference is that F# and Elixir are backed by industry whereas Racket is primarily backed via academia. Thus, the incentives and goals are more aligned for F# and Elixir to be used in industrial settings.

Also, both F# and Elixir gain a lot from their host VMs in the CLR and BEAM. Overall, F# is the cleanest language of the three, as it is easy to write concise imperative, functional, or OOP code and has easy asynchronous facilities. Elixir supports macros, and although Racket's macro system is far more advanced, I don't think it really provides any measurable utility over Elixir's. I would also say that F# and Elixir's documentation is better than Racket's. Racket has a lot of documentation, but it can be a little terse at times. And Elixir definitely has the most active, vibrant, and complete ecosystem of all three languages, as well as job market.

The last thing is that F# and Elixir have extremely good notebook implementations in Polyglot Notebooks (https://marketplace.visualstudio.com/items?itemName=ms-dotne...) and Livebook (https://livebook.dev/), respectively. I would say both of these exceed the standard Python Jupyter notebook, and Racket doesn't have anything like Polyglot Notebooks or Livebook. (As an aside, it's possible for someone to implement a Racket kernel for Polyglot Notebooks, so maybe that's a good side project for me.)

So for me, over time, it has slowly whittled down to F# and Elixir being my two languages that I reach for to handle effectively any project. Racket just doesn't pull me in that direction, and I would say that Racket is a bit too locked to DrRacket. I tried doing some GUI stuff in Racket, and despite it having an already built framework, I have actually found it easier to write my own due to bugs found and the poor performance of Racket Draw.

This looks very similar to LiveBook¹. It is purely Elixir/BEAM based, but is quite polished and seems like a perfect workflow tool that is also able to expose these workflows (simply called livebooks) as web apps that some functional, non-technical person can execute on his/her own.

1: https://livebook.dev/