I finally decided since this is just a stream of consciousness build log at this point I don't need to burden myself with coming up with headings for posts.

There isn't even a sensible structure around the post boundaries. I basically just make a new post in here each day and when I come back during the same day I generally just add a horizontal rule separator.

I think things are shaping up quite nicely and the roadmap from the last post is good, but I think there is slight refinement to do on the page sorting. So far the pages sort by git date (and I definitely need to do much more comprehensive testing on that, because it's supposed to function properly in a fully recursive way, and I don't have any deeply nested example posts committed to git yet, but that's okay for now), and there are already a few posts where my original sequence of insertion is not reflected well.

Actually I reviewed it and thought about it some more, and there is only a single anomaly, the fact that the "7.1.deep.md" got sequenced between posts named 1 and 2. I had of course created and git added each of the pages in incrementing order consistently.

Basically what happened was I really did throw an initial markdeep test post file into git as the 2nd file in this dir and then later on i pulled most of that content into the post named "7.1". Per git's content-addressed following behavior, it decided that what is now 7.1 is the second page that I added, and honestly there is a lot of truth to that. Edit: In light of this, to keep the naming consistent i will simply rename this (fairly useless tbh) post "1.1" shortly.

So perhaps if I want to more tightly control the ordering of certain pages I could add a feature to mark pages as exempt from date ordering, I don't know how I would want that to work right now. And it shows that other than this, the git --follow originating date resolution is working great now. One thing I may want to add later on is to also introduce the time range to individual posts.

I also began a high level refactor to reorganize the code from one single stage file into 5 or so files. I asked aider/sonnet 3.5 to come up with three architectural approaches and review them, and the results are pretty good. I am able to gradually perform the refactor while the build continues to pass, and it is going quite smoothly. Since I'm in a lull with that right now, I'm going to try to see if i can work in the special main blog page index summary.

I was reviewing some of the "business logic" in my build (It's currently referred to as a "stage" process) which handles rendering out the markdown I write into HTML for publishing to S3 and there's really a lot of potentially arbitrary choices being made in the logic. They are sensible choices for a blog so it makes sense baking it into a script like it is. Here is the precise example I am referencing:

I have a system now for assigning dates to show for pages to give readers a sense of chronology and how outdated my information might be. I have blog post pages and I have "summary pages" for blog series (previously referred to as "sagas") where, like this one is the 20th or so post in the series, I can put many posts into a directory and the directory gets its own page that presents a navigation list for all posts inside it, and if I choose to create an index.md it will show that content as well.

Now what i thought was going to be useful (and it is working really well) is to evaluate these computed dates for all of the children posts and populate the series summary pages with a date range. This works well to reflect the time range of a given project and nicely saves me from having to do the manual work to update all of these dates when I make updates.

So one of the little quirks here is that I explicitly exclude index.md files from having their original-insertion-into-git dates considered for this time range calculation. The idea is that actual content pertaining to a project or topic goes into actual post files, and index.md files are for describing what's inside a directory of posts, something that I might instantiate a long time after I'm done creating the content inside.

It's pretty clean and sensible logic, but if you consider this logic outside of the context of a blog engine it would probably look really arbitrary. It reminds me of how many configuration-centric tools like Ruby on Rails function -- they are implemented as what's basically an elaborate script that allows you to modify behavior based on configuration. In practice I've found working with such tools to be frustrating because I usually stray far away from the happy paths that brought these frameworks their success and recognition, so I tend to get stuck with not enough configurability (as the framework creators would have had to have considered my needs ahead of time and deemed them important enough to accommodate), unable to quickly resolve those problems without delving into source code. The problem with the source code is it would be either not available or so heavily encumbered by the weight of all the configurability as to be totally impractical to work with with any regularity.

Of course, maintaining high quality documentation can put a big dent in these issues, but keeping it up to date is often difficult. Maybe it's impractical, but I think the holy grail is for code to be so clean and so perfectly commented (in terms of clarity, conciseness, and accessibility) that documentation isn't necessary.

It used to be a necessity in the early days for software to be bundled with documentation. But these days if your application can't be totally figured out by almost everyone who attempts to use it without any assistance, then it's basically a failure. I think it's just like this. Maybe the stance is a bit extreme, but I think it's true that if you have some code that is so cryptic that it requires extensive documentation or commenting to keep collaborators from misusing it, then it simply has not been factored well.

This ties back to one of my visual programming concepts (which I will expand on at great length soon) where I believe that most of the friction involved with software boils down to simple tractable programming language constructs. It's just that there are so many of these constructs and so much creativity on tap from programmers that we often get beaten down by what is essentially the sheer unintuitiveness of Someone Else's Code. Sometimes when we are frustrated we like to proclaim things like, This Code Sucks or that something is overengineered. What I believe is that regardless of how much we think some bit of code sucks, or how overengineered something might be, better tools to help us cut through and make sense of these overwhelming layers of abstraction will function like a tide that lifts all boats.