hitchstory VS Monocypher

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.

I rarely got to know the actual deployment scale of anything I've done. Let's make a list:

Ground software for an observation satellite. My internship was about implementing a dead simple neural "network" (2 hidden layers, no feedback), everything was specified from up top, we didn't even get to touch the learning algorithms. Impact? I guess a big flat zero, since all the differentiators was in the learning parameters.

Peer-to-peer social network before Facebook. Never made a cent.

Geographic Information System for the military. I was for obvious reasons not allowed to know enough to estimate the impact of my work. And even then all decisions was made by the customer, and once the user (a different entity) saw the Rube Goldberg contraption we dully made for them they predictably balked, and we did what we could from there. Which was, not that much. I did some useful stuff for sure, but mostly I participated in a system that was arguably worse than the one that preceded it.

A visualiser for civil radar data. Data in, little planes in the screen out. And other nice stuff. I designed a simple C++ API that allowed the client to write business code faster than we would have ourselves (if only because of communication overhead), saving weeks of work. That contribution was utterly ignored for personal reasons, and I was eventually out. I have no idea what my actual impact was, because I don't know how far the project even went, and how widely it was eventually deployed.

The maintenance of ground software for small civil observation drones. I did some cool stuff, but then was asked to transfer ownership of this software to a recently bought team (that did stuff similar to the company I worked for). I could have known how many drones were actually deployed, but to be honest my thing just saved a few minutes of flight, while most of the cost is to get the drone and its operator on site. That company was never really profitable, I hope the good people I met there are doing well.

Scripting language for a programmable logic controller test environment. For the military, so I don't think I was allowed to even know the size of the team we'd deliver the software to. I got good feedback from them (they were happy about what I did), and I'm pretty sure my static typing made things easier for them than if I had just picked Lua or something, but how easier, and how much money it will save in the long run I have no freaking clue.

Stuff in a missile company I cannot disclose. I believe my impact was almost nil, I couldn't stand their abysmal tech environment.

Prototype ADAS system. It was never deployed. Actual impact was therefore basically nil. Cool stuff to work on though, the CAN bus is a think of beauty. One of the rare instances where I could actually learn from example, instead of seeing yet again one of the gazillion obvious ways how not to do stuff.

Ground software for some IoT device. Impact fundamentally uncertain, we had yet to sell it to anyone.

Incident reporting software, based upon a more generic distributed base. I made the encryption layer (between users & company server), with a security based on PAKE (thus avoiding a PKI, which simplified the work of the sysadmin, at a slight loss of security). Impact fundamentally uncertain, we had yet to sell it to anyone.

Charging stations for electric vehicles. I did the TPM provisioning, and mentioned a low-key security issue along the way. I participated in a questionable micro-service that was meant to help user interfaces (yeah, their IoT stuff had a micro-service architecture). Impact: whatever I did didn't save them: one year after I left, they're now going under.

Preliminary study on the possible use of AMD-SEV to prevent users from peeking at our secret sauce (DRM). I don't think I was allowed to know the list of clients, and it's not even the only alternative. I don't think I could ever have assessed the long term impact of my work there.

Flight recorder for trains (not a flight recorder then, but you get the idea). I just did little tasks here and there, didn't get the chance to have a good bird's eye view of the thing or its environment. Deployment base was knowable, but the business impact of my work was likely minimal, beyond "finish this step so we can show the client we're on track for the next short term milestone". The whole thing is a heap of technical debt, common components are impossible to update (user projects aren't locked to a given revision, they all pull from trunk), the build system is a home made monstrosity that doesn't help more than the standard monstrosities (I hate build systems)… and I was just axed from a round of layoffs.

Cryptographic library I did on my free time: https://monocypher.org/ Nice little thing with a significant user base in the embedded ecosystem (not even my primary target). I controlled everything from start to finish, and I have no idea how many users I have, let alone how much time and money I saved them. In part because it is so simple, with such an outstanding documentation (which I mostly didn't write), that most users don't even have to bug me.

---

To sum this up, my resume looks fairly horrible with respect to what I know of my actual business impact. Most of it, I think, was entirely outside my control. And I don't think I'm exceptional in this.

As the dictator author/maintainer of a tiny library¹ (45 functions total), I can confirm the manual wouldn't be half as good without external contributions. And I daresay this manual is a major contributor to the usability of the whole project.

As a new user of libcurl, I was recently able to quickly implement FTP upload and adapt it to our specific use case thanks to their tutorials and API documentation. I was even made aware of the lack of thread safety in old versions thanks to that same documentation, so I could warn my team that we should update.

Documentation is bloody important. Almost as important as the code and the test suite themselves.

[1]: https://monocypher.org

Are you assuming I didn't already do that? For your information I've written an entire cryptographic library in C https://monocypher.org and routinely chose C over C++. My claim that C is broken beyond repair doesn't come from ignorance or hype, it comes from over 15 years of first hand experience.

And of course, GC and RC aren't fixes, they can't apply in the performance constrained settings C and C++ typically are used for (tiny embedded chips, video games, video encoding…).

Also there's no way I'll even look at a new language without some form of generics. They're just too damn useful. Sure we could try the Go approach and special case generics for a few core data structures, but I believe a general purpose language needs a way to add custom ones. Heck, even Go fixed its mistakes and added generics after all.

Compilers don’t find all the optimisations. Last time I saw this was when someone noticed that my code was 5% slower than the reference implementation. This patch fixed it.

Every time I'm faced with OpenSSL, I think, "This is even more of a dumpster fire than I remember." My expectations are low, and it never fails to come in even lower than that. It's ugly and difficult to use. A good crypto API won't require all this resource management because it can all be done with small, fixed-sized buffers. In the future consider Monocypher or libsodium.

If encryption performance is not that important (especially on the client side, which I expect won't use too much bandwidth), but you value minimising dependencies, consider using Monocypher instead of libsodium. Monocypher is a single-file library that has absolutely zero dependency (not even libc). The price to pay for that is (i) right now it's slower than libsodium, and (ii) it doesn't provide an RNG, you'll have to call your OS's RNG manually.

I'm not yelling at you for your choice. See here for how hypocritical it would be of me.

This website does a pretty good job of going over what the creator of Monocypher found to implement Elligator. There’s also this Python code which has comments detailing the steps.

I believe my coding style is best shown by example. Some people have called it impressive. Some others have called it the worst they've ever seen. This may or may not come from the domain: cryptographic code tends to be pathologically straightline. At the very least it tend to produce longer functions than other domains.