🎙️ Episode #53: Refactoring English: Writing and Self-Publishing with Michael Lynch

TMPDIR Podcast
1

Episode Description

Technical writing for developers with Michael Lynch, author of Refactoring English. We cover structuring a book for reader ROI, cutting aggressively, using AI as a teacher instead of a ghostwriter, and a self-publishing toolchain built on Asciidoctor, Nix, and Hugo.

Available on your favorite podcast platform.

In this episode, Michael Lynch returns to discuss finishing and self-publishing Refactoring English, his book on effective writing for software developers. Michael is a former Microsoft and Google engineer who founded and sold the TinyPilot hardware business, and writes about indie software at mtlynch.io.

  • Where the book stands: written out of order over 19 months against a six-month estimate, now in its first full read-through, with a 1.0 release targeted for mid-August. He treats the ebook like software — ship 1.0, then keep improving.
  • Why a writing book for developers when 80–90% of the techniques are universal: the value is in the framing and the examples — commit messages, pull request descriptions, and design documents rather than generic prose.
  • Structuring for return on investment. Reader surveys said one thing and reader confusion said another, so he ordered chapters so that someone who stops a third of the way through still gets the most value. Chapter two is a single page: read your writing aloud.
  • Writing in your own voice. Readers rejected a chapter on “content marketing” and accepted the same material as “finding customers through blogging” — people buy the book because they want his thinking, not the expected framing.
  • AI and writing: why relying on AI parks you at a local maximum, and Michael’s rule that AI should act as a teacher and never write into your documents.
  • The biggest anti-pattern he sees in developer writing — meandering into implementation details before establishing why the reader should keep going — and the journalism parallel of the inverted pyramid.
  • Writer’s block, focus, and phase separation: writing and looking things up are different activities, and mixing them costs you the flow state.
  • Releasing in public: a Kickstarter that went from 60% to 120% of goal in the final days after a Hacker News front page, and how early access feedback supplied motivation more than it supplied edits.
  • Cutting aggressively — publishing less than half of what he writes, “kill your darlings,” and using a Git repo as the safety net that makes cutting easy.
  • Self-publishing lessons: regional pricing (and why Stripe makes it harder than it should be), cross-promotion learned from an indie romance novelist, and roughly 600 customers to date.
  • The toolchain: Asciidoctor for PDF, HTML, and EPUB output and its limits on layout control; Nix for reproducible builds and pre-commit checks; Hugo for the website; a custom word-word tool for repeated words;
  • Cliff suggested Typst as a Word replacement for nicely formatted PDFs like datasheets.
  • Reading recommendations: The Elements of Style, Joel Spolsky’s software writing, and Write Useful Books by Rob Fitzpatrick.