It's probably time I start talking about AI, because it's fundamentally changing everything I do on a day-to-day basis as a manager and tech writer. I'll bloviate on this from a managerial perspective at a later date, but I thought I would start with a basic example.
The problem
This blog was a Jekyll web site, doing the docs-as-code thing, taking Markdown and using a static site generator to spit this out and publish it on GitHub Pages. Good stuff, but because of life, I haven't touched it in... well, years. It happens. But almost four years have passed, which is in web-time is like if I was carving this stuff on clay tablets.
I was sure there was a better approach. I mean, I've gone through three of them at the day job, and I know there's bigger/faster/stronger out there. Also, I have no idea how many blatant security holes this thing might have, how many outdated packages knocked around, how many different ways GitHub changed their publishing process.
But, I'm completely out of touch with the Jekyll world. I haven't used it daily since I left TIBCO in 2021. Not only is there no muscle memory in how the site worked, but I don't know what the cool kids are doing anymore. I have a great Marketing Engineering team at work that's on the leading edge of this stuff and have the daily at-bats behind them to do this. But they don't handle my personal blog, and I've definitely worked in places where I didn't have a dev team dedicated to my docs site.
The old way
Nobody reads this blog and there's no money involved if I mess it up. But let's say this was a docs site at a Real Company doing Real Business. How does the typical update or repair scenario usually go down?
- I don't know how to fix it.
- I go to a dev group in the company. It's not their job. They have a job and it's at 400% right now.
- I go up the chain. A manager higher than me says, "I thought you did that."
- I bounce around a few other dev groups. I get either "how does this affect ROI?" or "I've got 19 things on my roadmap that are shipping this month" or "That sounds like a great idea! Let's talk next month" or "I thought you did that."
- I consider hiring a contractor. Back to step 3, but "how does this affect ROI? How much does this cost? Don't you have a developer? Did you ask (person from 2)."
- Maybe if I look at ancient posts on StackOverflow I can figure this out?
- Goto 1.
This is not a good process. And it happens to me like once a month.
The new way
I am a Codex apologist. Claude Code seems to be the cool thing these days, and I use that too. But I'm paying for ChatGPT here at home, so Codex it is.
I fired up Codex, pointed it to my GitHub repo, and asked this:
This Jekyll site hasn't been touched in almost four years. What has changed with Jekyll that may need to be updated, and are there any package or library changes that need to be made?
Codex chewed on this for a minute, ripped through the site structure and dependencies then proceeded to tell me exactly what had changed in the Jekyll world in the last four years. Jekyll 4.2.1 was the new hotness and I was still on 3.10.0. The theme got a bump too, and I had some customization to the theme that needed adjustment. Change those and that changes a bunch of stuff downstream, but that's all handled through the magic of the Gemfile.
GitHub Pages completely changed their publishing method, and I'd either have to stick to the old legacy way or move to GitHub Actions. I totally would have missed this. And I'm sure many fine people work on GitHub's docs, but RTFMing this and trial-and-erroring it until it worked is a week of my life I can't spare. It was amazing that Codex told me all of this, and gave me a plan of action and the steps to take. Now I just had to make a choice on the two methods, and have Codex do the rest:
Align the migration to native github pages dependencies. Do this in a GitHub branch and open a PR
There was a brief stumble with getting the latest GitHub CLI running and then logging in. But otherwise, two lines, done. It created a PR, I gave it a test spin, and then I merged. Flawless.
I cannot emphasize enough how much of a pain it would have been for me to do this myself. Instead of asking permission and trying to explain this in meetings and getting back the wrong thing, I literally typed two lines and had "someone" else do the entire thing to me. If you've been in this predicament before, you can see this is absolutely life-changing.
Bonus points: switching tools entirely
This was awesome and it worked. But let's face it, Jekyll is a bit “is the dress blue and black or white and gold?” date-wise, and I thought, "Why not just move to a newer tool?"
I used Gatsby for years, and I liked it. I absolutely know there are newer static site generators, but Gatsby would be a good test case. So:
This site is jekyll and I want to move it to Gatsby. I would like to change it from jekyll to Gatsby. Let's break it up into the following big tasks:
- Create a branch jkgatsby and do the work there, as a PR.
- Any structure moves that need to be made to switch to Gatsby, including moves of configs and such.
- Use the gatsby starter https://www.gatsbyjs.com/starters/gatsbyjs/gatsby-starter-blog/
- We still want to use .md. Do whatever you need to convert in the frontmatter. If _posts isn't the preferred directory for gatsby, feel free to move it.
- Build the site with a github action when anything is pushed onto main.
- Put a header or menu somewhere that has the about, contact, skills, and resume pages.
- Take the twitter reference out of the footer.
Codex took a few moments to sing the song of its people, and spat out a PR. I had a follow-up on getting pagination going, but that was quick. I merged the PR, and had a brief GitHub Actions fail, but when I explained it and Codex looked at my config, and realized that was botched up a bit. It explained a settings change, and I did that, and it 100% worked.
A few years ago, I ran into a similar-but-different GitHub problem with HTTPS configuration. This took days of reading three different conflicting sets of docs, Googling endlessly to find other blog posts that didn't have the right answer, and way too much trial and error. This time, I asked a question, got an answer, had a complete implementation ready to review and merge. Done. Back to work.
There are obvious philosophical, political, and cultural arguments about this. More on that later. But this is an absolute game-changer, and it's completely changing what it means to be a manager, now that I can manage my own AI "team" of developers.