mattyblog

Write yourself a README

ersatz.website/~mattyblog is a static website. Every time I make a post I need to perform a number of small steps to get that post onto the internet. When I wrote my last post about using a split keyboard I screwed up the steps and caused my entire blog to 404. The reason this happened is because I hadn't made a post in several months and just forgot how to do it.

Part of the solution to this problem is using a README file. If you aren't some flavor of software developer or some kind of sadistic computer hobbyist, you may not have ever heard of a README. Wikipedia defines a README simply as a file that "contains information about other files in a directory or archive of computer software". README files in different projects don't all contain the same information but some common things that are usually included are installation instructions, usage instructions, and things of that sort. The file is intended to be used as a quick reference for the software it is paired with.

I had a README file for my entire ersatz.website project, but it was out of date and incomplete! This is a common problem!

Because I use the Digital Ocean App Platform, I have to "deploy" my generated static site to a github repository. The App Platform watches that repo for changes and then deploys my site automatically for me. This is normally great! This repository lives as a sub-directory in the main ersatz.website repository. I have a Makefile that generates all of ersatz.website and places it into the output repository that the App Platform uses. This is slightly complicated due to having to use a separate repo to store the output of the static website generation. Normally you might have your build pipeline building the site for you, but I am limited by the App Platform on Digital Ocean to simply deploying the generated results until I can figure out how to have their application platform build pipeline to run my Makefile with all the required dependencies.

The steps I need to perform are

The App Platform then updates the deployed website.

My README file contained none of this information. The README is exactly where these steps should have been documented along with why these steps need to be performed. Six months is a long time between posts and it isn't any surprise that the deployment steps were forgotten. When I was fixing the problem I also had to re-discover why my deployment process is a little convoluted when fixing bad deployment. Normally whatever projects I work on contain a README - this one did - but it is super easy to fall behind with updating it when other things seem much more important. I think writing blog posts felt more important than documenting how the actually nitty-gritty details of the deployment process worked.

Accidentally taking my blog offline by (somehow) pushing the wrong stuff to the git repo hosted on Github that the App Platform uses was a fantastic reminder to make sure that I keep my README file up to date with any relevant information I'd like to have if I came back six months later and forgot how everything worked. I use READMEfiles written in Mardown in most of my projects, and you should too so you don't get yourself into the situaton I got into.

Like I said, a README is only part of the solution to this deployment snafu. Whenever multiple steps are required to do something critical, it is always a good idea to consider writing a script to perform all the necessary actions automatically and correctly. I had a Makefile defined to perform all the steps required to generate the site, but the deployment was still a largely manual (and annoying) process to kick off. Perfect for a little script to do for me.

I'll probably get to that later. Maybe. I am writing this post first.