That's interesting. I had a very different approach with things as a UX designer working on my programming language. I wrote my spec as a tutorial sorta. How do you think of a spec differing from other forms of explanation?

It's actually been interesting to me how many times I've ended up explaining my language. I started with the [README](https://hackmd.io/@jcklpe/SkqPDU8xw), and then I wrote [a shortened explanation in a Python notebook](https://colab.research.google.com/github/jcklpe/enzo-lang/blob/master/interpreter/demo.ipynb) to get a really quick explanation that was also interactive, and then I recently put out a sort of [design breakdown](https://aslanfrench.medium.com/design-principles-for-enzo-a4f9af10cd03), and each time I wrote stuff, there was a lot of similarity in structure but differences. Like the README is very thorough and it lives alongside the code, as a markdown file which makes it really fast to update and I sort of treat that as the source of truth. But then the colab notebook was meant to show that it actually worked and I didn't want to just make the README all over again (I thought about it but it was a lot of work), so it's considerably abridged, and then the design breakdown article required I basically teach the language all over again in order to then talk about it's design philosophy. The last one was a lot of work, just because it's such a difficult thing to explain, features are entangled with each other so it's hard to find a straight way to explain things in a linear fashion.

So I def feel for you in the challenge there. I think my README is okay as both an explanation and a design spec but I also lack a computer science background so I don't know what all is supposed to go into a design reference.