{"@attributes":{"version":"2.0"},"channel":{"title":"Sarah Deaton","link":"https:\/\/sdeaton.com","description":"On AI, developer tools, technical writing, and whatever else catches my interest","generator":"Zola","language":"en","lastBuildDate":"Sat, 16 May 2026 00:00:00 +0000","item":[{"title":"Making All Caps as a Service","pubDate":"Sat, 16 May 2026 00:00:00 +0000","author":"Unknown","link":"https:\/\/sdeaton.com\/blog\/making-acaas\/","guid":"https:\/\/sdeaton.com\/blog\/making-acaas\/","description":"

For my recent Write the Docs talk<\/a>, I needed a docs site that felt real enough to demo against. I didn\u2019t have a convenient API lying around to document, so I built a toy API and a full docs site on top of that; overengineered, but did what I wanted and it was a fun side quest.<\/p>\n

This is the full walkthrough of building ACAAS, All Caps as a Service<\/a>. Looking back, I thought it was an interesting, abbreviated case study in some AI\/docs tooling and building a site from scratch, so I wanted to jot down the decisions and steps.<\/p>\n

\"ACAAS<\/p>\n

1. Build the service<\/h2>\n

First, I used the Claude Code CLI to build a small API from scratch. I gave it the concept (you send text, it sends it back in all caps) and asked it to make it realistic enough to write docs against (like rate limits and error messages, and a few endpoints). It chose Python for the backend and came back with a few new endpoints like \/shout<\/code> and \/whisper<\/code>, and the supporting machinery to go with them.<\/p>\n

I also told it I wanted one AI-powered feature, ideally something on the path to GA; a feature graduating from experimental is the kind of documentation moment I wanted to demo (and every SaaS company needs an AI feature). It proposed \/experimental<\/code>, which uses a small model to decide which words in your sentence deserve to be bolded.<\/p>\n

After it finished building the API, I ran \/simplify<\/code>, which is a bundled Claude Code skill<\/a> that does a quick cleanup pass to look for dead code and unnecessary indirection. This wasn\u2019t important for anything, but I wanted to at least feel like the code was cleaner than a one-shot pass. Then I ran \/init<\/code><\/a> to generate a README and CLAUDE.md. The README is for future me, in case I ever need to run or modify this thing again. The CLAUDE.md is just good practice at this point, the scaffold I\u2019d want if I came back to this project for something else.<\/p>\n

2. Find a documentation platform<\/h2>\n

My first instinct for the docs platform was Zola<\/a> or Astro<\/a>. But before choosing, I did a sanity check on Mintlify<\/a>, which I\u2019ve worked with professionally for a couple of years and have never tried spinning up for a personal project. I\u2019d assumed the free tier would be limited in some way that didn\u2019t fit a one-off demo site, but it wasn\u2019t. I created acaas.mintlify.app<\/a> in about a minute, cloned the repo, and was ready to go.<\/p>\n

I was mildly embarrassed not to have known about the free tier. I also kind of want to move my blog over to Mintlify now.<\/p>\n

\"The<\/p>\n

3. Design the site<\/h2>\n

I didn\u2019t need to do this step at all, but it was the most fun. I have 0 design sense whatsoever, and Claude Design<\/a> has been a lifesaver for me. I started a new prototype, described what I was building (\u201ca Mintlify docs site for a fake API called All Caps as a Service\u201d), and it started guiding me through the design steps until I had a lovely new branded docs site.<\/p>\n

\"Two<\/p>\n

I like that Claude Design asks clarifying questions as it works; things like what kind of feel I was after (bold or minimal or standard SaaS), whether I had color directions or wanted it to pick, etc. I landed on a theme I was happy with, had it generate a favicon and logo to match, and the whole time it was working inside Mintlify\u2019s design constraints rather than producing something I\u2019d have to retrofit. When I was done, I chose the \u201cHandoff to Claude Code\u201d export option and went on with my day.<\/p>\n

\"Claude<\/p>\n

4. Apply the design<\/h2>\n

I used Claude Code Desktop for this because it has a built-in local preview. I could run the site locally and watch it render while Claude made changes, and Claude can see the preview too, so it catches its own rendering errors without me having to describe what I\u2019m seeing. The workflow felt closer to pairing than to instructing. You could also do this with the CLI and then use the Claude in Chrome extension<\/a> or Playwright MCP<\/a> to have Claude iterate on the design itself locally, but I just like the Desktop in-app experience.<\/p>\n

\"Claude<\/p>\n

This step was pretty anticlimactic in a nice way. Claude took the design handoff, implemented it cleanly, and there wasn\u2019t anything to debug. As an aside, I\u2019ve shipped so many ugly, half-finished prototypes and waved it away with \u201cI don\u2019t like CSS,\u201d and it feels like the days of that are finally over.<\/p>\n

5. Scaffold the docs<\/h2>\n

I let AI generate the content with little direction, and I feel very fine about that. I said I wanted getting-started guides, cookbooks, and a changelog, and it produced them. I\u2019m sure a few are confidently wrong in ways that don\u2019t matter for a demo.<\/p>\n

One thing that surprised me was that new Mintlify sites ship with a pre-built AGENTS.md<\/code> file and a .claude\/<\/code> directory with settings and skills scaffolding for working with Mintlify, along with some basic style guides. The core instructions felt fairly useful\/didn\u2019t include anything I\u2019d argue didn\u2019t deserve to be there.<\/p>\n

6. Create an OpenAPI spec<\/h2>\n

The last piece was an API reference section. This is one of my favorite Mintlify features, even though the docs I work on now don\u2019t have an API component. The API reference pages are built in and include an interactive playground where visitors can make live calls to the service from inside the docs themselves. All it needs is an OpenAPI spec, which Claude Code generated directly from the service code.<\/p>\n

\"The<\/p>\n

\n

Start to finish, the whole build was about two hours, most of which was the design step and a small detour deciding how much realism the rate limits needed. A year ago I would have spent the same two hours scaffolding just the initial API and decided nevermind maybe I\u2019ll go a different direction.<\/p>\n

End result: I used the demo in my talk, the git commands I avoided for nine years<\/a>.<\/p>\n"},{"title":"The git commands I avoided for nine years","pubDate":"Fri, 15 May 2026 00:00:00 +0000","author":"Unknown","link":"https:\/\/sdeaton.com\/blog\/git-talk-recap\/","guid":"https:\/\/sdeaton.com\/blog\/git-talk-recap\/","description":"\n

I recently gave a talk<\/a> at Write the Docs<\/a> about three git commands I\u2019d been avoiding for most of my career, or in two cases didn\u2019t know existed at all. For the demo environment behind the talk, I built All Caps as a Service<\/a>, a fake API and docs site that turned into its own side quest.<\/p>\n

To properly set expectations up front: I\u2019m not a git expert. I\u2019ve used git almost daily for a decade with a workflow I\u2019ll describe in a minute, and recently discovered some parts of git that changed my thinking on it. I gave the talk and wrote this post because you don\u2019t need to be a git expert to get a long way with the tool, or to look into the parts you\u2019ve been avoiding.<\/p>\n<\/iframe>\n

\"Sketchnote<\/p>\n

Sketchnote by Dennis Dawson<\/a>, via the Write the Docs Flickr<\/a>. I love the reflog drawing.<\/em><\/p>\n

How I got here<\/h2>\n

For the majority of my time in tech, I used about six git commands: add<\/code>, commit -m \"wip\"<\/code>, rebase -i<\/code>, commit --amend<\/code>, cherry-pick<\/code>, push<\/code>. Add, save, clean up the history, polish, and push. It worked, and it produced nice clean PRs.<\/p>\n

When I first learned git in a software engineering bootcamp, the framing was unambiguous. Git was esssential but could be dangerous. You could lose work, and you should stay inside a small set of safe commands. Above all, don\u2019t touch rebase while you\u2019re learning. If you got into a mess with it, you were on your own.<\/p>\n

I eventually went to work on teams with other engineers, learned about collaborating on projects using git, added git rebase -i<\/code> to my toolkit, and felt pretty accomplished. My daily git commands worked for the most part\u2026 except for the few times when I\u2019d do a bad rebase, and think I lost hours of work, despair and start over. Or get into a really tangled merge conflict and just end up deleting the branch and pulling down again from the remote. I thought that was the way it was; git was powerful with some rough edges.<\/p>\n

What changed this for me had nothing to do with git initially. Last year, I wanted to run two Claude Code sessions on the same repo on different branches at once, purely for parallelism. I didn\u2019t know how to do this, because as far as I knew, you could only have one branch checked out for a repo at a given time on your computer.<\/p>\n

The fix turned out to be git worktree<\/code><\/a>, a git feature rather than anything to do with Claude Code. It also addressed a paper cut I\u2019d been living with for years that I didn\u2019t even realized I\u2019d had: the stash-checkout-checkout-back-stash-pop dance every time I wanted to spin up a quick branch for a typo fix when I was in the middle of other work. Fixing a problem I hadn\u2019t let rise to consciousness made me wonder what else was there and what I should incorporate into my toolkit.<\/p>\n

The three commands<\/h2>\n

I picked these three commands because they were the most directly useful ones that I found, and, in the case of git reflog, changed my view of git entirely.<\/p>\n

git worktree<\/code><\/h3>\n

You\u2019re mid-edit on a quickstart change, and someone asks for a one-line typo fix on a different branch. The dance is git stash<\/code>, git checkout main<\/code>, git checkout -b typo-fix<\/code>, fix it, git checkout quickstart<\/code>, git stash pop<\/code>. So much context switching and heaven forbid you get pulled away in the middle of it and have to remember where you were in the dance when you left off.<\/p>\n

Worktrees solve this context switching problem. The command git worktree add ..\/typo-fix main -b typo-fix<\/code> makes a second working directory on your machine, pointing at the same repo, on a new branch. Then you can cd into that directory (..\/typo-fix<\/code>) and have two branches open at the same time, without needing to wind down\/stash your work from one task to switch to the other.<\/p>\n

The worktrees share the same .git<\/code> history, but all the files are duplicated and won\u2019t clobber each other as you make changes in each branch. The quickstart edits stay sitting in the original directory, untouched. Open the new folder in a second editor window, fix the typo, push, and the original is exactly where you left it.<\/p>\n

When you\u2019d reach for it:<\/strong> any time you\u2019d otherwise stash or do the checkout dance. Especially worth it if you context-switch between branches a lot.<\/p>\n

When it shipped:<\/strong> 2015, a year before I started learning git.<\/p>\n

git reflog<\/code><\/h3>\n

A pronunciation note: it\u2019s ref-log<\/em>, short for \u201creference log.\u201d I\u2019d always pronounced it git re-flog<\/code>, which made it sound made up and was a primary reason I didn\u2019t investigate it any further. Based on the people who came up to me after the talk, I\u2019m not the only one who did this. This is also the one command that made me rethink my whole vision of git and realize it\u2019s so much safer than I\u2019d been taught.<\/p>\n

git reflog<\/code> shows everywhere HEAD<\/code> has been recently (every commit, reset, checkout, rebase, all of it). If you ever accidentally git reset --hard<\/code> too far or drop a commit during a rebase, or get a tangled git history through a merge conflict, this is the command that saves you. The \u201clost\u201d commit, or the good place you used to be but now aren\u2019t, is sitting right there in the reference log. You can always go back to it. Just run git reflog<\/code>, find the SHA for the commit\/place in time you want to return to, and git reset<\/code> back to that place.<\/p>\n

The piece that finally clicked for me, which I\u2019d been missing when I was taught: HEAD in your repository is just a pointer<\/strong>. Doing something like reset<\/code> or changes branches moves the pointer, but the commits themselves don\u2019t go anywhere. reflog<\/code> is the trail the pointer left behind, kept for 90 days by default.<\/p>\n

The one catch is that it only saves committed<\/em> work, and uncommitted changes blown away by reset --hard<\/code> are gone. Commit early and often!<\/p>\n

When you\u2019d reach for it:<\/strong> any time you think you\u2019ve lost work or are in an otherwise irreparable state.<\/p>\n

Neat trick: I also learned recently that you can even do things like main@{one.week.ago}<\/code> to go back to where your main branch was a week ago. You don\u2019t even need to find exact commits but can say things like \u201cI knew this was working two days ago, let\u2019s go back there.\u201d<\/p>\n

git rebase --update-refs<\/code><\/h3>\n

You have a stacked PR (branch A off main, branch B off A). Someone lands a change on main that conflicts with A. The naive flow is to rebase A onto main, resolve the conflict, then rebase B onto the new A, where the same conflict is waiting for you to resolve a second time.<\/p>\n

git rebase --update-refs main<\/code>, run from the top of the stack, rebases the whole stack in one pass and moves the branch pointers along the way. You only need to resolve the conflict once, and then all the downstream branches get updated with the changes from main as well.<\/p>\n

When you\u2019d reach for it:<\/strong> stacked PRs that should all get updates from a branch at the same time.<\/p>\n

When it shipped:<\/strong> 2022. I\u2019d originally planned to talk about git rerere<\/code> (it remembers a conflict resolution and replays it next time the same one shows up), and found --update-refs<\/code> while writing the talk.<\/p>\n

The one I think actually matters<\/h2>\n

If you take one of these home, take reflog.<\/p>\n

Worktrees and --update-refs<\/code> are about ergonomics and make day-to-day tasks easier. Reflog is different; it changes the belief that screwing up means losing work, and that belief was what kept me out of the parts of git where the real power lives.<\/p>\n

For the record<\/h2>\n

A few QA questions where my live answer was either hand-wavy or wrong, because again, I\u2019m not a git expert at all. Here are my corrected answers (and thanks for the opportunity to learn this with you all!)<\/p>\n

git worktree<\/code> vs. multiple clones<\/h3>\n

Someone asked what the actual difference was between doing git worktree<\/code> vs. just having multiple cloned versions of your repo. A clearer answer than whatever I gave:<\/p>\n

Multiple clones give you fully independent copies of the repo, each with its own .git<\/code> directory. Branches you make in clone A don\u2019t show up in clone B until you push and fetch, and you\u2019re paying for the full history twice on disk.<\/p>\n

Worktrees share the underlying .git<\/code> (the secondary worktree has a tiny .git<\/code> file<\/em> pointing back to the main one). Branches and commits show up in every worktree immediately, with no fetching and no duplicate storage. The one constraint is that the same branch can\u2019t be checked out in two worktrees at once.<\/p>\n

If you want two separate copies of the project that can drift apart, that\u2019s git clone<\/code>. If you want one project with multiple working directories so you can sit on two branches at the same time, that\u2019s git worktree<\/code>.<\/p>\n

Does reflog work with reset --soft<\/code> and --hard<\/code>?<\/h3>\n

Yes for both. I also want to walk back something I said on stage, because I had it backwards. Every form of git reset<\/code> moves HEAD, which is the whole point of the command. The flags change what happens to the index and working tree on top of that:<\/p>\n