When you are creating a new library you a design in mind. Sometimes that design does not appear when coded. The code is cumbersome to use. Nothing flows right and requires a lot this and that special methods to make it all right. It is a mess.

This happened to me recently. I am working on a library that generates CI/CD pipelines files. Each file and format is different but they underneath the syntax they are the same.

I wrote the first implementation and it was difficult to use. Yes, it worked but I hated using it. And this is coming from the developer who wrote it.

I was out of ideas and needed to move forward. So I looked at the existing body of software to find something that matched what I was doing. I am building files. If you want you could call them documents. My documents have blocks in them. This is all very similar to the Document Object Model for HTML.

Now, I am not copying the DOM IDL but I am copying how it feels. You can rant against the DOM but it has stood the test of time.

You work on a document. Elements are created in and added to the document. In the end the document is rendered. It turns out this is exactly what I wanted to do.

So far I am liking my adjustments. The DOM inspiration was the best way for me to move forward. I now have mental model of how things should work. It is helping.