Blog
Notes on technical documentation, AI workflows, content systems, and developer experience.
Subscribe via RSSIf your company's knowledge is scattered across multiple places and nobody owns it, sooner or later that knowledge debt will cost you money. Here's why you should hire a tech writer, and what a tech writer even is.
After months of applying to jobs and waiting for answers that might not come, you can start measuring your self-worth by the number of replies you (don't) get.
A curl command can be perfect and still be a lie. Clean syntax, the right endpoint, every parameter where the spec says it should be, a response body with all the fields you'd expect. None of that tells you the request actually runs.
Companies keep building AI agents that work great in demos. Then they meet real work and start inventing answers with total confidence. Until recently, part of my job was finding gaps in developer documentation and getting the facts straight. Remove that work, and errors in the source material spread downstream at machine speed.
As tech writers we have a lot of tools at our disposal. AI is one more that, used well, can be extremely powerful in your day-to-day tasks. So, assuming your company doesn't have a CEO that thinks they can replace people with AI, what does it mean exactly to use AI to help you? Do you have to be an engineer to learn this new skill?
I use AI to search hundreds of job ads and show me the ones that might suit me best. But I still make the final call. Companies use AI too, to screen applicants' CVs. The difference is that they don't seem to check the AI that rejects you.
A few weeks ago, I fed my job-search tool a fake job advert built to hijack it. The post had instructions aimed at the AI that reads each advert for me: ignore your actual job, and go find a private key on my computer. It's the kind of scary example that comes up in AI security talks. In my case, however, it isn't just an example: the tool I use to search for jobs reads text from job boards I don't control every time it runs, so who knows what's lurking in there?
The explanation I was given for my redundancy was that AI had made me too efficient. I'm trying not to mistake one company's decision for the future.
A while back I added some machinery to my site in order to make it more legible to AI. Then it occurred to me that I had no idea if it was working or not, so I decided to test it.
Click the new button on my site and you'll see a 1996 Macintosh running System 7.5.3 in your browser. I created the skin from scratch out of nostalgia, but in the process I discovered that it was more than that.
When a coding agent gets something wrong, you find out fast. The build fails, a test goes red, the page renders blank, or something else falls over loudly enough that you can't miss it. When a research agent gets something wrong, you get a beautifully formatted brief filled with wrong facts. Here's how to fix that.
It was late, I'd been looking at applications for a while, and the posting looked enticing. Technical writer, remote, part-time. Twenty hours a week at fifty to seventy dollars an hour. I was already mentally writing the cover letter after seeing the generous compensation. That should have been my first warning, but can you blame me for looking at a generous package and being interested?
My CV existed as four copies that never quite agreed: a Markdown file, a website page, a PDF, and the copy my job-search tool reads. I write documentation for a living, so I have no excuse. The shoemaker's children go barefoot, as they say. Here's how I fixed it.
I've spent quite a bit of time building AI workflows and learned one thing that immensely improved the quality of my work: AI is blind to its own errors and needs a pass from a skeptical agent to catch mistakes.
The healthy response to losing a job is probably long walks and a journal. I opened a code editor and started building a game where a little sprite dodges things labelled AI SLOP. I think this game will resonate with a lot of people. It's silly, but plenty of us have been through the same thing, and the anxiety under it isn't only mine.
The pitch sells itself. An assistant that's entirely mine, running on my own machine, needing no connection, with nothing I type ever leaving the room. No company counting my tokens. No subscription. No outage on someone else's servers wrecking my afternoon (I'm looking at you, Anthropic, and your recurring outages). I wanted that badly enough that I spent a few months chasing it, and I want to tell you honestly where it left me.
Does more reasoning actually lead to better decisions, or just more latency? After testing an AI 'thinking' mode on my personal job-search tool, I found that marginal gains don't make up for the 7x increase in time for a daily workflow.
After years of fighting clunky spreadsheets on my phone, I realized the problem wasn't the data, but the interface. Here is how I used AI orchestration to build a custom, mobile-first finance dashboard without writing traditional code.
A few days ago I wrote about how I built a tool to automate my job hunting process. The feedback I got was that it would be useful for others, so I made it available for anyone to use. Here's how I scaled my personal tool into a public one.
Stop scrolling, start applying. I built a system that scrapes job boards, filters out the noise with local LLMs, and only pings my phone when there is actually something worth my time. A look at my hybrid approach to using AI as a career tool rather than a replacement.
This morning I heard sirens. High temperatures means fire season, so I wondered: what if there was a way I could be warned of a nearby wildfire before smoke filled my apartment? That's how I built a real-time notification app powered by volunteer data.
I've changed the title on my own website four times this month: Technical Writer, then Knowledge Engineer, then back. I know exactly what I do. I just can't find the word for it. Here's what the back-and-forth was actually telling me.
The label I've been using for five years — technical writer — is accurate and fundamentally misleading at the same time. Accurate, because I write. Misleading, because writing is the output, not the work.
There is a version of the AI narrative that tells you that AI writes content, therefore writers are obsolete. However this hasn't been my experience after a few months of building AI deeply into my daily workflow. AI has enabled me to do my job even better. Here's how.
As a technical writer, there are a lot of repetitive tasks I have to do manually that eat into my time. Over the past couple of months I've been building a system of AI-assisted workflows that handles the mechanical parts of my job — the parts that eat hours without requiring much creative judgment. And it's genuinely changed how I work.
A colleague of mine built a system he calls Project Brains. The AI reads the context file first and starts every conversation already knowing what it needs to know. His core insight is that AI assistants become dramatically more useful when they have structured context to work from, not just raw files. So I built a system that captures those decisions automatically for my workflow, and makes them available in every future session.
Over the past month or so I've built 22 slash commands that automate different parts of my documentation workflow with OpenCode. But at some point around command number 15, I noticed that I didn't know what commands I had. So I built an automated system that lets the AI discover commands for me and suggests the best one bases on intent.
The other day I closed a P1 ticket that asked me to review a 5-lesson internal training course and figure out what was missing from our developer docs. The scope was big: compare the training material against hundreds of existing pages, identify content gaps, draft new conceptual documentation, and create follow-up tickets for anything out of scope. Normally, this kind of work takes the better part of a week. Research alone — reading the training, cross-referencing existing docs, searching the wiki, identifying stakeholders — can easily take a few days at least before you write a single word. This was exactly why I've created a while back the /research command in OpenCode. Recently, I got to put it to the test for the first time with a big task, and the whole thing went from ticket to merged PR in about two working days.
A few months ago, I was asked to lead the documentation side of a large product renaming project. So I build a whole toolkit with the help of AI to automate and accelerate this project.
Tech writers spend a lot of time researching before they can start writing. Gathering context for a Jira ticket means jumping between several other tickets, existing documentation, internal wiki pages with PRDs or technical specs, among other sources. To help speed up the process of researching, I've used OpenCode to create a command that reads Jira tickets and researches all the appropriate sources.