I write about docs and knowledge engineering
Hi, I know it's been a while since my last post. Things have been nuts in my personal life and I've also been hella busy at work onboarding someone new. I've just generally had a lot on my plate. Good news, though, I've been building a lot of stuff and maybe, JUST MAYBE, some of this might benefit you! Here are a few more things I'm doing to combat slop and bad outputs, generally. skills writing…
We've all seen AI slop online. We've all seen people wailing about the glut of AI slop. We've all seen people concerned about how their AI usage might impact their own ability to create content unaided. I think about this a lot, because I use Claude for so many tasks at work -- I genuinely don't want to draft technical content from scratch anymore. My professional skills and natural abilities are…
I recently hired a human technical writer to work on my team. Although I have so much I want to say about the process of hiring, I have to keep things professional and appropriately vague. What I can do, however, is give you some high-level insider tips (now that I've seen inside the applicant tracking system (ATS) machine). This advice is not a magic spell that will get you a job. Tech writing is…
I recently got my first pair of progressive lenses. For those who don't know, they're eyeglass lenses that have multiple prescriptions to allow the wearer to see at various distances. They don't have any visible lines like bifocals or trifocals. They're wildly expensive, and despite my initial claims that I only needed glasses for reading at night, they've changed my life for the better. I had…
I've used RescueTime at nearly every job I've had since I started tech writing. My first-ever tech writing manager used it as a tool to micromanage the interns (I even had to log bathroom breaks). That didn't sour me on time tracking, though. Time tracking is beautiful . Time tracking creates useful data I can use to inform (or defend) choices I make at work. Time tracking helps me meet my goals…
Hi! Happy New Year! I started the year by doing a super fun podcast episode with Tom Johnson and Fabrizio Ferri-Benedetti. I was sick for 30 days in December. I had a cold, then Flu A, then one blissful day of feeling great before I was struck down by some dramatic ear thing with a terrible cough. I read a lot of books and I slept a lot, and I eked out the work I could. I feel like I'm still…
(I didn't actually throw my Samsung Galaxy S21 into the sea, it's in a drawer) Anyone who has ever spoken to me for more than four minutes knows that I'm not really a "tech" person. All I actually want to do is grow herbs and putter in the garden. I didn't have a cell phone until I was in my 20s, and even then -- it was prepaid and I only turned it on when I needed to call someone. background (aka…
I've been scripting the boring and repetitive parts of my job since 2014. I started with little stuff, like a simple "integration" that allowed me to update content in a support desk application's APIs for their built in CMS (RIP Desk.com). Looking back now, it was a very early docs-as-code workflow. From there, it just spiraled. I scripted running reports, updating version numbers, changing…
It's been a busy few weeks for me professionally and personally, and I'm finally getting a little time to sit down and write another post. Today I want to talk about how and why I use the terminal and various CLIs for tech writing tasks. A few writers I've talked to are a bit intimidated by the command line, and I think my biggest hope for this post is that the more CLI-reluctant among us might…
I recently had a post published on the Payabli blog. It's all about how I scaled our docs team with just tools and two people. You can read the original on the Payabli blog . I think that I might write more about individual elements of the scaling project. If there's anything in particular you'd like to hear about, reach out on any Slack workspaces we may be in together, LinkedIn, or email…
Recently, I built an AI-powered testing tool that simulates different user personas navigating documentation with a defined goal to measure success rates, identify navigation issues, and help find actionable insights for doc teams. I managed to do this in 7.5 hours of screen time, and at no point did I abuse Claude so heavily that I hit my session limits. My entire thesis was that documentation…
I'm obsessed with API definitions. I love REST APIs. I don't know if this has any connection to my utter obsession with the J Crew and LL Bean catalogs in the 90s, but I get the sense that they're connected in some way I can't articulate yet. I've documented plenty of APIs but I've never actually built one before. I decided to build a very simple static JSON content API for docsgoblin.com (this…
Throwback post from 2015 I wrote and published this waaaaay back in September 2015, and I recently dug it out of my old GitHub account to share it again here. Publishing slightly edited cause everything I wrote 10 years ago feels cringey. I was talking to a colleague about documentation, and he apologized about how his notes were a "bad first draft" of a proposal. Without even thinking, I blurted…
Originally posted sometime in 2015 At my 90-day review at my first technical writing position, I got some feedback that ticked me off: 'unleash your writing freedom' or some other corny-sounding thing. What my boss was getting at was that I was too rigid about writing. It's true — I used to be a stickler about grammar and usage. I ran around correcting people on the internet and making a big deal…
posts June 27, 2026: slopaganda countermeasures, part 2 March 17, 2026: slopaganda countermeasures, part 1 March 13, 2026: some tech writing job hunting tips, from a hiring manager February 6, 2026: a new lens January 14, 2026: using time tracking to manage time January 06, 2026: new year, same me December 07, 2025: throwing my smartphone into the sea December 03, 2025: build your own CLI and…
I got a burst of creativity or maybe it was that Dr Enuf I didn't have any plans this weekend, so I decided to figure out how much cool stuff I can build between Friday night and Sunday night and still have time for my typical weekend activities. something flashy Friday night I sat down and planned out a tool I thought might be helpful to me in my day job -- an AI-powered tool that approximates…
Relative links continue to humble me Picking up from part 2 of this tale , this post is going to cover how I created the script that creates the markdown snippets that I can reference in my pages. I don't really want to write it myself, but I know exactly what I want it to do. I start with the outline: Load relationships.yaml Index all document frontmatter from pages/**/*.mdx Build lookup…
I wish all relationships had schemas Yesterday, I posted a grand plan to add what amounts to a modern see also element built with a relationship mapping file (see part 1 ). Now, let's think through the relationship schema I want to apply. So far, I know that I want the mappings to live separate from the content, so I'll put them in a file called relationships.yaml . I still need to define the…
How to use frontmatter and scripting to map relationships One of my favorite features of DITA is the reltable (relationship table), which lets you explicitly map relationships between pieces of content. I'm not currently at a DITA shop, and I've been mulling over how to build some sort of explicit relationship mapping that makes sense for my docs. I've been thinking about it even harder since I…
DOCS LIKE STRIPE. WE WANT DOCS LIKE STRIPE. Every tech writer has heard this. At a previous role, WE WANT DOCS LIKE STRIPE was directed at me, with full eye contact during a meeting, by a leadership team that refused to give me any money for tooling or development resources. I cracked and said "Stripe has like seven engineers on their doc tooling alone, I'm not sure what you expect from me with my…
Picking up from yesterday's csv export experiment , I have big csv file with a bunch of gaps I don't want to manually fill if I don't have to. This morning, I sat down with my first cup of coffee and gave myself permission to spend 20 minutes tinkering before changing my tack. trying with claude.ai So, I asked Claude: Hi there! I need to craft better seo stuff for many fields. Can you take a stab…
Sometimes, as doc owners, it's good for us to try to make Marketing happy. To that end, I set out this week to do a full SEO audit of our doc content to make sure we're using all of the SEO tags that Fern suports. We have a lot of doc content and I'm lazy, so this morning I gave myself however long it took to drink my first coffee to figure out how to make the process as fast as possible. 15…
I was a fairly early adopter of genAI at work — as soon as security and leadership allowed, I started using various AI chat interfaces to make my job faster. It started simple, with prompts like "Please convert these bullet points into a markdown table". Then one day I had the bright idea to use Claude to refactor a collection of bash scripts I used in our docs-as-code workflow, and my usage has…