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.
Nice! My rule (pre-AI) had always been never force a human to do what a robot can. If you can automate yourself out of your least favorite part of your job, that's a win for both you and your employer. You can move on to more meaningful work, or in some environments, just leave early. Reminds me of that old xkcd about the tradeoff in time between doing something manually vs. automating it.
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/
I've gotten that feedback before. Once a lawyer, always a lawyer.
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.
Glad to inspire. That was the point of the post. For the record, I never made any guarantees that the book (or the website) was any good. Software or prose, you can have the most pristine build pipeline in the world, but "garbage in, garbage out" as they say.
Your own descriptive comment got downvoted and the only other comment I see is bashing you.
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 think you’re way off. Hate is absurd, I don’t even know him. He’s automatically being downvoted for hyping his own product on HN, although he’s certainly not plugging it too hard.
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.
Nice! My rule (pre-AI) had always been never force a human to do what a robot can. If you can automate yourself out of your least favorite part of your job, that's a win for both you and your employer. You can move on to more meaningful work, or in some environments, just leave early. Reminds me of that old xkcd about the tradeoff in time between doing something manually vs. automating it.
How did people come to the conclusion that "over-engineered" is something positive?
What gives you the impression that "people" have come to such a conclusion?
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)
Well, there goes my weekend. Thanks for sharing. Will take a look.
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!
Ha! Indeed. Love the time-lapse video.
ETA: Need to add "maniac on the front page of Hacker News" to my resume.
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.
I've gotten that feedback before. Once a lawyer, always a lawyer.
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.
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!
Glad to inspire. That was the point of the post. For the record, I never made any guarantees that the book (or the website) was any good. Software or prose, you can have the most pristine build pipeline in the world, but "garbage in, garbage out" as they say.
Textbook example of structured procrastination. I bet you got all your household projects done as well as taxes for next year
Thief recognizes another thief… ;)
I saw myself in OP’s write up, the process is nicely described.
Okay, but I feel assured your book will be astonishingly boring.
Why do you think I procrastinated writing by building out all that unnecessary tooling? /s
Your own descriptive comment got downvoted and the only other comment I see is bashing you.
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 think you’re way off. Hate is absurd, I don’t even know him. He’s automatically being downvoted for hyping his own product on HN, although he’s certainly not plugging it too hard.