How I over-engineered my book(ben.balter.com) |
How I over-engineered my book(ben.balter.com) |
I expected him to talk about Java, and lessons learned about it writing the book (he did not start nor end in Java and documented a number of programming languages.)
What we got instead was a rundown of how he 'overengineered' the book. He had interns solving a problem for him: How to make sure the published code examples actually run when transcribed into an editor.
They wrote a tool to mark up live code with extraction points to excerpt it automatically into his manuscript.
About five years later I worked at a F50 company with a bunch of contractors who were all Getting Shit Done and making some of the more bureaucratic org units around us a bit nervous. Someone thought they found a gotcha by complaining about how our developer documentation didn't meet the defined documentation standards the company had devised. They weren't wrong, but people used to the platform we were building on wouldn't have been stymied at all by what we gave them.
If we had done it the way they suggested, it would have added almost a week of my time to every release, and I was already struggling with delegating enough work to make me not the bottleneck. So that extra week would have taken our velocity down a notch and made us a bit more comparable to everyone else. It was a clever ploy, but Bruce saved me.
Instead of spending a slog every release on updating the docs, I found that Bruce's strategy had already been made into a FOSS tool, jcite. So I spent about 50 hours the first quarter learning to use it, and fixing up all of my integration tests to be suitable to use the way Bruce taught me.
With that done, it took less an hour per release to fix the developer documentation, and half of that hour I got one of our tech writers to take off my plate (I couldn't get the documentation template to exactly match the corporate template, so she manually fixed the handful of errors). So within another quarter we were back to full speed. It's possible I imagined the disappointment when we explained what we did but it was a delicious hallucination if so. Nice try. Maybe you could learn from us instead of trying to pull us down with you, hmm?
Thanks Bruce, for teaching me a lesson I didn't even know I needed.
These are both strong tells of AI-generated prose, though I find it surprisingly difficult to articulate exactly why. It makes me wonder whether your style has evolved to sound more like AI-generated prose, or whether AI-generated prose has evolved to sound more like you!
(disclosure: I wrote it)
> "Please add in this repo, a pre-commit hook in the form of a script that prints all filenames and line numbers on which the hyphenated "open-source" string exists, and if any instances are found, will exit nonzero. Then please install it in `.git/hooks` so commits are blocked until me or an agent removes all the instances, so we never again commit the string "open-source"."
1 minute after hitting enter you've created yourself a guarantee your repo will never again see the string "open-source".
Full disclosure, a few months back when I had some tokens expiring, I had Copilot spike out a draft to see if there was anything "there" worth writing. If you check the revision history (linked from the bottom of the post), I did a full (human) blank page rewrite three days ago and then only used Claude for line edits like adding links or fixing failing lints.
You did a "blank page rewrite" of a 576 page book "three days ago"?
Ended up with Org-mode. Emacs with a bit of customization color- and font-codes richly. Org text goes into an Org-to-HTML converter that I hacked up in Go, incrementally added to as new wants arise.
Most recent completed production was a photo album for relatives. In HTML form, it could be put on line, but I used Weasyprint so I could give them self-contained PDF as a keepsake.
In an over engineered thing margin is left on the table which the consumer gets to take advantage of. Noting that in the real world items are often exposed to loads and demands above and beyond the idealized design constraints a 'perfectly' engineered item would just meet.
From the article itself: "Over-engineered, absolutely. [...] Every check earned its place by catching something I’d otherwise have shipped. Would I do it again? Without hesitation."
And I hear you about over-engineering. I feel like a Linux user--spending more time getting my laptop just right instead of using it. I have to remind myself that the point of it is the result, not the process.
If our two styles found a middle ground we'd be unstoppable!
ETA: Need to add "maniac on the front page of Hacker News" to my resume.
I saw myself in OP’s write up, the process is nicely described.
This is the only correct use of AI IMHO. Including for development.
This is inspiring because I can indeed make a website, and have a lot of drafts that I want to turn into a book!
But in this article, the TLDR and first paragraph have textbook LLMisms. The landing page for the book is clearly vibecoded both in structure and copy. This is very alarming for material that is meant to market a book, which I expect to not be vibe-written.
So whose book is this, actually? What otherwise could be a very useful lesson comes off as a trojan horse for automated viral marketing slop in order to promote a book which I have to assume at this point is vibe-written. To be clear, I use AI heavily in my work today, and understand the difference between AI-assisted work and vibe-coded work. This appears to fall in the latter camp. How much editorial control did you assert over this project? Where did the ideas come from? How do I know a given snippet is a well-researched fact or the product of experience, instead of an unfounded potential-hallucination?
I've also been making websites for decades, Ben, and most people I know in that camp are more interested in letting their hard-earned experience elevate their output to the top of the pile in an increasingly competitive space.
If this is the direction we're going in, vibe-coded marketing campaigns and vibe-coded landing pages for books that we rationally have to assume are also vibe-coded and basically a medium for Claude, then we as authors must adopt an atmosphere of clarity and transparency towards our audience. A book like this needs more information about the process so that people like me don't immediately and rationally disregard it as slop. I can see your blog goes back to 2011 so I want to give you the benefit of the doubt and a chance to explain yourself further.
It seems you rub people the wrong way, but so far I'm scratching my head as to why you're receiving this degree of hate. Is this common for you? Does someone have a vendetta against you?
> I’m not going to tell you to write 5,500 tests for your novel. For most books, most of this is wildly disproportionate — and that’s the point.
> One of these caught me. `validateHypotheticalHooks` flagged the opening of a paragraph I was certain I’d written myself — and I had. But reading it back cold, it did sound ghost-authored; I’d absorbed the cadence from reading too much generated text and produced a fluent imitation of nothing.
As for the book, "trust me, I'm human" isn't going to cut it here (we literally prove humanity on the internet by training robots to act more like humans). As I posted earlier in the thread (https://news.ycombinator.com/item?id=49337307), most of the book's chapters began as blog posts that I've published for over a decade, well before AI slop came into the picture. The book is those, refined. 2026 me can't Terminator myself into creating a retroactive paper trail.
And thanks for the feedback. Human Ben is going to take another pass at the post and rewrite those you flagged so that they don't take away from the message.
Count the number of times it brags about a specific quantity.
Count the number of false insights, sentences made to elevate the obvious into the profound.
Count the number of em dashes. Count the number of times an inanimate object or verb is used as a noun. Observe the textbook Claude design, full of glows and embodying all the worst aspects of web 2.0 landing page culture.
> Fun isn’t a distraction—it’s a retention strategy. Self-care isn’t weakness; it’s operational discipline
> The book in one page / The playbook, start to finish / Ten parts, each building on the last. Here’s the path.
The most alarming part is it appears Ben either did not bother to review and edit the content, or was not adept enough to recognize it as deficient. That didn't prevent them from posting it directly to hacker news via their own account without even a Show HN. They consider this material to be ready for an audience and that's concerning to me.
It's so very clear why he thought it was a good idea to have a regex validator to check that he doesn't imply he still works at Github.
"i dont work at github"
"Yes, you're absolutely right. I apologize for the mistake and have edited the document accordingly.
reads War and Peace system prompt
Here is how we can programmatically and scientifically avoid this problem in the future:
1. Add to the regex validator library: We can add to the regex validator library an additional entry to catch any future instances of this mistake. This is a low-cost, high-yield approach---regex runs with deterministic and repeatable results, with the added benefit that its big-O runtime scales at most linearly with the size of the text for most use cases (Hartmann, 2018).
*Three other braindead ideas*
Which future-proofing strategy shall we take?"
"sure 1"
This is how you people sound.
You can't recognize AI. Nobody can without training specifically to recognize AI, and eve then, it's only been shown to be successful with a language with an online corpus significantly smaller than English.
The thing LLMs are best at in the entire world is imitating human writing. So all you're really doing is discouraging a human from writing.
I hate AI in the artistic disciplines. No one hates it more than I do. But Jesus Christ, I've been seeing legitimate authors get called AI for over a year now, and it's so bad that I know people are quitting writing over it. ("What's the point, everyone stopped reading because they think I'm AI") End result being the percentage of writing that is AI goes up, and humans enjoying the most human of all disciplines goes down.
What I observed are overused, and recognizable, stylistic patterns that have become quite common in LLM generated prose. In this article alone there are three "here's the X" rhetorical signposts, well over a dozen neatly constructed reversals/antitheses ("not X but Y," "solved X and created Y"), repeated setup->complication->punchline paragraph structures, rhetorical questions used as transitions, and a high density of anthropomorphized technical metaphors.
None of these alone prove AI authorship. In fact their existence (and the authors own words!) are exactly the point I am making: his validateHypotheticalHooks linter flags "formulaic AI-tell openers," and he describes catching himself writing one because he'd "absorbed the cadence from reading too much generated text."
Let's return to a more positive discourse, and not immediately become vitriolic when someone rightfully points out that material marketing a book might not be genuinely produced by a human. We should expect more transparency from the author around the use of AI in their writing and marketing process if we are expected to give this book any attention.
Chapters built on an earlier post making the same argument:
- Why everything should have a URL → "Why URLs?" (2015) + "Expose process through URLs" (2014)
- Speak like a human → "Write corporate blog posts as a human" (2015)
- Optimize for developer happiness → "On stickers and optimizing for happiness" (2015)
- The zen of open and async work → "The zen of GitHub" (2015)
- Lead like an engineer → "Manage like an engineer" (2023)
- Rethinking management for remote teams → "Deprecate management" (2012) + "Cathedral–bazaar management" (2023)
- Retool your documents → "Word vs. Markdown" (2014) + "We've been trained to make paper" (2012)
- The etiquette of issues and pull requests → "Types of pull requests" (2015) + "Pull requests are a form of documentation" (2023)
- Showing colleagues they're valued → "Three easy ways to show employees you appreciate them" (2017)
- Choosing the right collaboration tools → "Tools of the trade" (2020)
- What I wish I knew before going remote → "Eight things I wish I knew my first week at GitHub" (2016)
- Career conversations → "The brag doc" (2026)
- Intro to software development for non-technical roles → "GitHub for non-technical roles" (2023)
And chapters that are near-verbatim descendants of a named post:
- Leaders show their work → "Leaders show their work" (2022)
- Work loudly → "Work loudly" (2026)
- Meetings are a point of escalation → "Meetings are a point of escalation" (2023)
- The Andon principle for knowledge work → "Transparency & collaboration is the Andon of knowledge production" (2023)
- Engaging with dissent → "Dissenting voices" (2024)
- How to 1:1 → "One-on-one playbook" (2026)
- Agentic workflows → "Agentic workflows" (2026)
- Why you should work asynchronously → "Why async" (2022)
I think as a proof-of-concept that a book and its marketing campaign can be executed from start to finish with a programmatic, automated approach, it's an interesting piece. It seems to be listed on multiple outlets, I'm curious how much that part of the process was able to be handled by agents vs being done manually. I would almost be more interested in a book about this process than the actual book.
And I do recommend applying a much stronger human-in-the-loop editing process to any material meant to market this book (and of course the book itself). Prior experience and taste are all we have left in this new era.
I didn't touch too much on AI in the book itself (since it's changing so quickly), but it was interesting to reflect that the fundamentals of 2012/2014 (Markdown, URLs, APIs, etc.) carry double the weight when we start thinking about machine readability.
> It seems to be listed on multiple outlets, I'm curious how much that part of the process was able to be handled by agents vs being done manually.
Entirely manual, and I suspect that's by design. I've never published a book before, so I did ask (non-agentic) AI questions about the process (should I use service X or service Y, should I do a pre-sale, etc.).
> And I do recommend applying a much stronger human-in-the-loop editing process to any material meant to market this book (and of course the book itself).
100% human in the loop. I wanted the public-facing presence to be reader-centric, not marketing/author centric, which I felt was the norm LLMs are trained on.
> Prior experience and taste are all we have left in this new era.
+100. I held the book to a much higher standard than I do musing I randomly post on the internet that hardly anyone reads. (I didn't expect this to get so much attention). I'm going to take another pass at both the post and the site tonight. Thanks for the feedback.