Script for consistent linking within book.

As part of my work on #eng-strategy-book, I’ve been editing a bunch of stuff. This morning I wanted to work on two editing problems. First, I wanted to ensure I was referencing strategies evenly across chapters (and not relying too heavily on any given strategy). Second, I wanted to make sure I was making references to other chapters in a consistent, standardized way,

Both of these are collecting Markdown links from files, grouping those links by either file or url, and then outputting the grouped content in a useful way. I decided to experiment with writing a one-shot prompt to write the script for me rather than writing it myself. The prompt and output (from ChatGPT 4.5) are available in this gist.

That worked correctly! The output was a bit ugly, so I tweaked the output slightly by hand, and also adjusted the regular expression to capture less preceding content, which resulted in this script. Although I did it by hand, I’m sure it would have been faster to just ask ChatGPT to fix the script itself, but either way these are very minor tweaks.

Now I can call the script in either standard of --grouped mode. Example of ./scripts/links.py "content/posts/strategy-book/*.md" output:

Example of ./scripts/links.py "content/posts/strategy-book/*.md" --grouped output:

Altogether, this is a super simple script that I could have written in thirty minutes or so, but this allowed me to write it in less than ten minutes, and get back to actually editing with the remaining twenty.

It’s also quite helpful for solving the intended problem of imbalanced references to strategies. Here you can see I initially had 17 references to the Uber migration strategy, which was one of the first strategies I documented for the book.

On the other hand, the strategy for Stripe’s Sorbet only had three links because it was one of the last two chapters I finished writing.

It’s natural that I referenced existing strategies more frequently than unwritten strategies over the course of drafting chapters, but it makes the book feel a bit lopsided when read, and this script has helped me address the imbalance. This is something I didn’t do in Staff Engineer, but wish I had, as I ended up leaning a bit too heavily on early stories and mentioned later stories less frequently.