Writing

This week a colleague taught me about Simplified Technical English in the context of agentic software development. I’m fascinated by technical writing techniques, so I intend to explore this. To start, I took ten instruction-like sentences from this blog, and asked ChatGPT to convert them to STE. Here’s what it came up with. The original sentences: Updating dependencies is good. Now, look at the console. Considering this result, think about another action you might take. You can remove it, and you ought to understand the consequences. Here’s some detail on how it works. Change a giant conditional to true! Be fast at committing code. In the real world, no two teams are going to use their data tools in the exact same way. For the salvageable tests, take a minute and fix them. Fix the commands and clear out the mail. And the LLM-generated STE sentences: ...

Want to get better at technical writing? I’ve been writing prose (READMEs, wikis, and this blog) with Vale for months. It’s helps me write better, faster. Here’s what I’ve learned. Vale is a “linter for prose.” It gives you tips like this. $ vale README.md README.md 4:3 error Did you really mean 'existant'? Vale.Spelling 6:12 warning Use 'use' instead of 'utilize'. Microsoft.Vocab 9:1 suggestion In general, use active voice. write-good.Passive ✖ 1 error, 1 warning and 1 suggestion in 1 file. It’s running in my text editor with Vim and ALE: ...

Prettier formats code in fenced code blocks! When I type three backticks and then a code, Prettier evaluates the code in the block and tries to format it per my global .prettierrc. I produce a lot of technical writing in markdown. I’ve often wondered if my fenced code blocks are valid, since I sometimes type them by hand. With Prettier, as long as I add a language identifier (e.g. typescript), that language is supported and configured for Prettier autoformatting, it will run on the block. ...

Always leave something behind. If you find something interesting, leave a trace that you were there. This is a little thing that over time leads to a friendlier, more humane internet. Here are a few examples. Blog post that helped you Imagine you’re reading a blog post and you find it helpful. Or, you agree with it, but find one part of the argument lacking. Before moving on, leave a comment! ...

Today I gave a talk to my team about the Twelve-Factor App Methodology. The Twelve-Factor app is an important methodology for building software-as-a-service drafted by developers at Heroku in 2011. It outlines best practices for app setup, portability, deployment, and scalability. I chose to share this because I think it’s relevant to all software engineers, and part of our shared language and conventions. And, I want the teams I work with to follow it, and for each of us to be a champion of its conventions. ...

Eight years ago I wrote a post called You Should Blog. In it, I made an argument that I still believe in: public, professional writing is something every engineer should try. Today, I want to share why I write, and have for over a decade. It’s made me better The first reason is that over time, I think it’s made me a better programmer. To give you an example, here’s an opinion I hold, and how writing helped me solidify it: ...

I’ve been organizing Meetups for a decade, starting with Vim Chicago and Chicago Elixir, and now running Maine JS from Portland, Maine. Here’s my practical guide on how to start a Meetup group, based on what’s worked for me. How to start a meetup group The steps that follow are in rough order. You’re going to be doing many of them in the beginning; that’s the time when you do the most sustained work. ...

I’ve been a practitioner of Shawn Wang’s ‘Learn in Public’ for years. In this post, I’ll share a list of ways I’ve found to learn in public. I think that learning in public can start with you, then your team, then the world. And so, these are ordered from small and private to big and public. Talk through a tough problem out loud. Instead of holding a difficult problem in your head, try building a solution out loud from a series of facts. “We’re seeing a bug on staging. It affects this page…”. Talk to a duck if nobody is around. ...

When preparing feature development work, I write Gherkin-style tickets, which follow the “Given/When/Then” format. Many people call these stories, and I do, too. This technique is incredibly effective! But why? In this post, I’ll try to answer that question. I learned this technique watching the greats at Hashrocket. They’ve been doing it this way since 2008 because it works. I have two complementary arguments for this technique: images and raw text hide complexity, while stories reveal complexity. ...

I’ve been giving technical talks for a few years, and I’m speaking at the Vim Chicago Meetup next month about integrating React with Vim. In this post, I’m going to use that opportunity as an excuse to document my speaking process. Some smart people have written on this subject, and anything I’d have to say is partly inspired by these ideas: Conference Prompts: Or How to Submit Proposals and Influence People How to Prepare a Talk Improve Your Presentations In Under $50 Speaking.io What I learned from reading 429 conference proposals What Your Conference Proposal Is Missing Several of these writers talk about submitting conference proposals, AKA CFPs. I don’t plan to cover that in-depth. Why not? I believe once you can write a compelling proposal, getting accepted is the product of a variety of factors you can’t control. So, submit many proposals, and be like Thomas Jefferson, who once said: “I’m a great believer in luck, and I find the harder I work the more I have of it.” And in the meantime, learn to give a great talk. ...