How I over-engineered my book

hyperhello

Okay, but I feel assured your book will be astonishingly boring.

t-kalinowski

Seeing that list of tools you're using in automations, I'm guessing you'll enjoy this, as another tool to add to the pile: https://t-kalinowski.github.io/yamark/ (disclosure: I wrote it)

khaki54

Textbook example of structured procrastination. I bet you got all your household projects done as well as taxes for next year

hinkley

I saw a Bruce Eckel talk one time after Thinking in Java became a best seller. 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.

stephantul

It is perhaps ironic that I find this post very difficult to read. I'm super interested in the content, but it reads like it is generated.

song_synth

hey thanks! I learned from your article that "if you can make a website, you can make an ebook." This is inspiring because I can indeed make a website, and have a lot of drafts that I want to turn into a book!

goostavos

In contrast, here's how I under engineered my book lol: https://news.ycombinator.com/item?id=49336392 If our two styles found a middle ground we'd be unstoppable!

_def

How did people come to the conclusion that "over-engineered" is something positive?

nonethewiser

The software engineering workflow is simply the GOAT for text based work.

TeaVMFan

Related: a tool to convert HTML to EPUB, with checks and smarts: https://frequal.com/epublish/

sinab

Thank you for the demo! I like the concept. However, I personally find that the writing style you've designed for reads very strongly as AI-generated. For example, opening a section with phrases like "Here's the irony: after automating everything up to this point," or "Turning emoji into images solved the missing-font problem and created a subtler one." 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!

soulofmischief

I agree with the premise and have also learned to apply my engineering habits to other domains that I normally struggle with. It helps a lot and allows me to churn through projects that previously would have not seemed tractable. 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.

everybodyknows

I set out likewise to write a highly structured book with FOSS, therefore: git, some hierarchical plain text format, and a visually rich editor. Markdown could not seem to meet the third point. For instance, progress-related comments that would be stripped from final output were essential, but Markdown's HTML-style comments are intolerably unergonomic, and editors know how to de-emphasize no other syntax. 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.

whiterook6

I love this! I'm writing short stories and I use Astro to build the site, I generate sharable qr codes and epubs for every story as well as the whole, and I use gh-pages to push to GitHub pages. 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.