Migrating from Docusaurus to Astro

Docusaurus was and is great, I even made a nice GitHub action for folks to use for continuous deployment to AWS and Azure. I have used it at multiple places I have worked for making internal documentation and other quick sites. The reason changing to Astro was:

1. To learn a new ecosystem, because learning is fun
2. I really like Astro’s resuable components
3. Astro, to me, is way easier to customize

How

The Astro Docs do a great job of explaining how to migrate from docusaurus if you are already set up. For me though, I went through the tutorial on how to make an Astro site from scratch first. I did this in order to understand how everything works. I made a super ugly site, messed with it a bit, then came back and used the cli to create the blog template. After that I just copied content over and then used their guide to deploy to Azure.

What’s Next

I hope to write more in 2026. I have learned a ton in the last few years moving from product tech to a gaming studio that I think folks would find interesting and I want to share more about my side projects and the learnings along the way.

First Job

My first “real” job was at the age of 14 (it was the early 2000’s man, wild times) and it was at McDonald’s. I was only allowed to work weekend mornings because labor laws or some such nonsense. I don’t remember why I thought it was a good idea or what I even said to convince them that they for sure should hire me, I just remember two things:

1. I wanted dollars, jobs gave you dollars
2. If they did hire me, I was going to be the best at whatever they were going to make me do

Turns out, there isn’t much they could let a 14 year old do on weekend mornings, which now makes me think, as I often think (hence the name of the newsletter) why did they hire me?

My job was to clean the dishes and utensils and things. This included baking sheets, spatulas, and various things for cooking eggs in. I made quick work of the baking sheets and the spatulas, but those dreaded dishes with eggs on them were the bane of my existence. You see, I was taught, if you are going to do a job you are going to do it right. In this scenario, in my 14 year old mind, it meant I was going to get every last spec of egg off of those things. I would scrub them into oblivion, because I was going to earn the heck out of my $4.75 a hour wage.

Turns out, scrubbing dishes to get every spec off of them is time consuming and kind of slow. Also an interesting fun fact, McDonald’s is a fast food restaurant and managers there at the time wanted things to not be slow, weird I know. Needless to say my managers kept giving the feedback that I was going too slow and needed to pick up the pace. I remember thinking, “how fast do they expect me to go?!” and “how on earth can I get these things spotless faster than I already am”. Then a bit on the negative side, “That is disgusting, they want me to not clean these things well?!”.

That was not the point, of course they wanted them cleaned well, but they did not need me to get every spec off of them because they were just going to be used again to make the next batch of eggs. They wanted good enough, not perfection. Which leads me to the lesson learned and how it applies to my job in tech

Don’t Let Perfection be the Enemy of Good Enough

I know that is not the saying exactly, but I like it better and this is my newsletter.

In software engineering, everything is about tradeoffs. If given all the time and resources in the world you can build the most beautiful perfect piece of tech, but that is not reality. In the real world, you have time constraints, resource constraints, tech debt, all sorts of things. When solving technical problems I find it best to focus on the business problem and the value proposition, then make your tradeoffs based on that.

You want to get the feature or the product in the hands of your customers sooner rather than later and then iterate on it. You want to obviously make sure it works, you want to make sure you think through things like performance, scalability, user experience, etc. but it is OK to ship with open questions.

When doing feature work, treat your design like a hypothesis and then use your userbase as a way to validate or invalidate it. A good hypothesis is a pretty good educated guess but there are unknowns and that is OK. Just ship the thing and see what happens.

In the case of my dish cleaning, what was more important, my crusade to remove all cooked egg bits from the dish or the long line of people who just wanted their sausage egg and cheese biscuit? The tradeoff to clean the dishes good enough instead of to the point of perfection was the correct one because it served the customers faster. It solved the business problem.