How To Write About Software | Jess Lin

Описание: Writing a technical blog post may sound like a solo task, but in reality it’s just like good software—best with a writer and reviewer/editor. But what does that process look like, and what’s the role of the editor?

In this talk, I’ll first show elements of a good versus great blog post, with examples. A good post gets the information across in an orderly fashion. A great blog post starts from great source material, and manages to be a page turner. Sometimes, good is all you need, but it’s useful to recognize when you have the potential for great.

Next, I’ll show real examples of specific edits to blog posts I consider good and great. In general, you need to first edit at the macro level (e.g. throwing out an entire first draft and choosing a completely different angle) and then the micro level (e.g. restructuring sentences for clarity). The title and opening deserve special attention, and I’ll share tactics you can use to write and refine them.

Marketing your software isn’t just for marketers. These techniques will help you in everything from pull request descriptions to release announcements. I’ll use real material from a series of blog posts we published in spring 2024 at Render to show how much of a difference applying editing craft to communications can make.

00:00 in this talk…
01:10 introduction and motivation
03:00 the three phases of the thought process
03:49 about me
04:22 about render
05:03 phase 1: getting started
06:26 goals and reasons to write
07:34 phase 2: find the angle
07:49 4 types of tech blog posts
09:40 applying the framework to Eric’s post
11:10 phase 3: write + refine
11:32 opening: before
12:18 opening: after
13:15 opening: another example
13:44 openings: think about…
14:20 headings: before
15:02 headings: after
15:55 body: making it skimmable
17:05 body: bullets
17:52 body: keep it moving
19:14 body: “info box”
19:37 title: before & after
21:24 ending
22:28 good v. great
23:45 the impact of writing on a reader
25:06 ingredients for greatness
26:42 closing thoughts on your next great blog post
27:00 audience questions and answers

I've been a software engineer for a decade. I first worked on an open source IDE at Facebook in 2013; then moved to ads at Pinterest, collaboration tools at Stripe, and absolutely everything at Instabase when it was only 5 people. In recent years, I've enjoyed roles that bring me close to users, first as a deployed engineer at Retool and now as a devrel at Render.On software teams, I've always found myself helping colleagues communicate their technical ideas. With my background, I can help engineers efficiently and with a lot of empathy. I’ve produced, written, and ghostwritten successful tech blog posts that have hit the front page of Hacker News and been featured in prominent newsletters.This talk came out of a colleague at Render asking me to explain all the edits I made to his posts (he could see the "what" but not the "why")—and SquiggleConf is the perfect excuse to sit down and explain!

---

SquiggleConf 2024 was the first edition of SquiggleConf, a yearly conference in Boston for excellent web dev tooling. See https://squiggleconf.com/ to learn more about SquiggleConf 2025: the second edition coming in September 18th-19th 2025 at the New England Aquarium Simons Theater.

SquiggleConf is a production of Squiggle.Tools, a nonprofit organization offering ongoing learning opportunities that enable participants to engage, learn, and advance their careers—regardless of their background or resources. If you want to support us, follow us on social media, and subscribe on YouTube.

BlueSky: https://bsky.app/profile/squiggleconf...
Discord: https://discord.squiggleconf.com
Mastodon: https://fosstodon.org/@SquiggleConf
LinkedIn:   / squiggleconf  
Shop: https://shop.squiggle.tools
X: https://x.com/SquiggleConf