I’m a tech writer by trade with a heavy focus on dev docs.
I’ve been writing my whole life, but I’ve also worked a bit in public education, and I’m a self-taught programmer.
I like to build things and break them to figure out how stuff works.
This is my place on the internet. It has a portfolio with some of my work and a blog where I can publish my own bits of writing and share stuff I like.
This is the category of behavior associated with problems the product exists to solve. It represents the first line of questions I ask when documenting a new product. Why does this product exist? Who is it for? When should they use it?
Work in this category is tractable. The environment is littered with clues that answer the most important questions: user stories, support tickets, architectural diagrams, design specs. I can piece together a mental model and produce useful drafts without touching a piece of working software.
Is this the most important thing I spend time on? Probably. Especially for new products. People won’t use something if they don’t know what it is or how to use it. Products without users fail.
When I’ve answered basic questions about why the product was created, I can explore whether it really does what it sets out to do, and how effectively it does it.
For example, the product is a door. A door exists so people can enter and exit buildings. If I’m helping people understand how to use the door effectively, I’ll look at how the door is designed. Where is the doorknob? How do you activate it? Which side of the door are the hinges on? Does the door swing in or out? Is there a mechanism for locking the door? Is the door accessible via ramp, stairs, or both?
I’m not going to answer all of these questions in my documentation. Ideally, the door will answer these questions through its elegant design. If I spend time documenting obvious affordances, I’m wasting my time and disrespecting my audience.
Instead, I’m looking for places where the product’s design suggests interactions that will fail. Places where the product suggests a mental model that deviates from real-world functionality. A doorknob on the same side as the hinges. A handle that only twists up. A push bar on a door that swings in.
This stage requires that I actually use the product I’m documenting. I bring design flaws to the product team that can do something to fix them. I provide adequate communication to enable user success when design flaws won’t be fixed. I slap a “PULL” sticker on the inside of the door.
In this stage I explore all the different things the product allows me to do that maybe it shouldn’t. The objective is to identify undefined behaviors and drive alignment on how we’re going to deal with them.
This is where tech comms finds a lot of overlap with quality assurance. This work involves a similar skill set as debugging. Personally, I think it’s the most fun.
When I discover undefined behaviors, I don’t document them, at least not right away. But I absolutely make a note of them, share them with the product team, and, if they seems like they might eventually cause problems that are a Big Deal to solve, see if we can make a plan to do something about them.
Spending time on this is often a luxury, but proactively dealing with undocumented behaviors can save a lot of money, headaches, and customer goodwill. Most successful APIs I’ve worked on have eventually had clients discover and code against undocumented behaviors in their downstream workflows. Teams with more visibility into their product’s undefined behaviors can make better judgements about the risks involved in changing systems as a product matures. At the very least, we sound a bit smarter when talking about our product to users who’ve baked our system’s undefined behaviors into their business logic.
TL;DR: If you want to customize your tables and you don’t want to start with Pandoc’s default reference.docx template, you need to create your own new table style, name it Table, and modify that style to do whatever you want tables to do.
I’m helping automate a documentation process at work, and the last step involves converting a Markdown file to .docx. The team we’re helping sent over a reference file with all their custom “styles” (in quotes here because none of the formatting they want to use is a style in the Word sense of the word).
We’re using this reference file as our template to apply custom styling when we run the conversion. We need to associate all the custom formatting in this doc with the Word styles Pandoc knows about so that Pandoc can apply those styles correctly. This was going fine until I couldn’t get Pandoc to apply our custom table styles.
It turns out that when you pass a reference.docx file to Pandoc, it applies any styles from the table style called Table to the tables in your converted document. I tripped on this because there’s no default table style named Table in Word, and the first Stack Overflow answer I came across suggested the solution is to edit the raw XML in your converted document.
I should note here that the Pandoc user guide does identify the table style from reference.docx as “Table”, but I don’t think that would have been enough for me to connect the dots. Also noteworthy is that when I google this on my personal computer, Google’s AI summary immediately tells me that I should create a new table style named Table. But Google’s AI summary is disabled on my work device, and I’ve had plenty of bad experiences using LLMs to troubleshoot Pandoc edge cases, so I thought I was making the smart choice by avoiding using the LLMs endorsed by our enterprise for this search.
I went about this the hard way, of course. Because it didn’t occur to me that I could just create a new table style called Table (or even to try this approach), I generated a new version of the reference.docx file, used Style Organizer to export that style to my own reference file, and went from there. I only learned you can indeed create your own new table style and even give it a custom, unique name (like, well, Table) until I started writing up this post to help other lost souls like myself and it occurred to me that I should probably just double check real quick that my workaround is indeed the only way to accomplish this task. Woe.
2025-11-15 update: I migrated this blog to Hugo and use Cloudflare for hosting, so this process is out of date. But I’ll leave it up for posterity.
I want to kickstart an extracurricular writing habit. I also want to write down the process I use to update this site from my iPad, so I can look it up after the writing habit has gone dormant and I need to remember how it all works. This post is a stone thrown at both birds.
I use Jekyll to build this site and GitHub for source control. For hosting, I have a Digital Ocean droplet running Ubuntu and Nginx. I followed this guide to set it all up: How to Install Nginx on Ubuntu.
To update the site from my iPad, I launch Safari and navigate to the repository with my source files on GitHub. From there, I hit . to start a codespace for my repository in a new tab. This codespace is a Visual Studio Code workspace loaded with the contents of my repository, all running in my browser.
I use this VS Code instance to make any changes I want to the source files. When I’m ready to build and preview the site, I open the integrated terminal for VS Code. I use bundle exec jekyll serve to update the contents of my _site directory and to check out a local preview that codepaces sets up via port forwarding. When everything checks out, I run an rsync command from the integrated terminal to send the contents of the _site directory to my server.
It’s a straightforward process, and the steps are pretty much the same when I update the site from VS Code on my laptop. Codespaces makes it possible to manage the whole process from start to finish from any device with a web browser.
Here’s a link to a Spotify playlist with a bunch of songs I like: Spin Cycle.
I think I’ll keep adding to this. I want an evergreen playlist with ten thousand great pop songs.
If you want an implementation of this idea by someone with much more interesting taste, check out Ben Watt’s Spin Cycle playlist. I love to discover music by learning what other people are connecting to, and people who have made their lives about music tend to make good recommendations. Ben Watt is generous in updating his public playlist on a regular basis.