A batch about writing well and about writing at all, plus a righteous rant that connects the two, starting with how to write an effective design doc.
Michael Lynch’s How to Write an Effective Software Design Document is an excerpt from his Refactoring English book, and it’s the best structured treatment of design docs I’ve read. The framing question that organizes everything (“what’s the penalty for being wrong?”) is what tells you which decisions belong in the doc (language and storage choices: yes; a “load more” button: no). He walks every section you might include (objective, background, goals/non-goals, scenarios, SLOs, security, open/resolved issues, alternatives considered) with real examples, and ships a full public design doc since he’d never seen a good one online. Even as a solo dev writing for future-you, the discipline of forcing the hard decisions before you code is the whole payoff.
Robin Rendle’s Several Short Sentences on Writing is the one for the novelist in you. Riffing on Verlyn Klinkenborg’s book, he lands on the idea that a writer’s real work is the endless winnowing of sentences, and that cutting long sentences into short ones is usually fear management, the urge to show off that you can write a sentence that never stops. The reframe that helps me: your job is making sentences, one at a time, which dissolves the overwhelm of a big project into something you can actually pick up. He also writes publicly precisely because knowing strangers will read it forces the winnowing. Directly useful for the HARDLOCK line-editing pass on The First Legion.
John Gruber’s What Is a Dickover? is a rant, and a glorious one. He coins a word for the modal panels, popovers, and full-screen curtains that obscure the content you came to read (cookie banners, newsletter nags, app-install pleads), the ones that “deliberately obscure their own content.” The Substack curtain gets a special beating, as do the sites that sucker-punch you after you start scrolling. His principle is one I keep coming back to: a webpage should show the webpage. It’s crude, funny, and completely correct.
Which leads straight to Jim Nielsen’s Blogging Can Just Be Stating the Obvious, a short piece written in response to Gruber. He fixes on Gruber’s aside (“I should not have to explain this”) and turns it into a small thesis about blogging: the best posts are often someone playing the child in The Emperor’s New Clothes, saying the thing that’s obvious to them but nobody else is saying. If someone’s already said it, just link them and shout “yes, this.” A permission slip for publishing, and a reminder that “is this even worth saying?” is usually the wrong question. (This is Jim’s second appearance in the series; he wrote the “pedantry of computing” piece a couple of batches back.)