Refactoring English: Writing and Self-Publishing With Michael Lynch

Show Notes

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.

Discuss this episode at our community site.

Hosts