There's some good advice in the book, but I found the majority of it seems to be rather goldilocks flavored. Implement the features you need, but don't add too many, but don't omit important ones either. Write some documentation, but not too much or too little. Etc. You read it, and oh yes, very wise, but not really helpful? Not much here would be useful in resolving a dispute between two programmers, one who wants to do things one way and one who wants to do it a different way.
People have a tendency to become extremists. I sometimes think of it as a ridge, with cliffs on both sides. People look at one of the cliffs, and back away from it, because it's a cliff, and it's dangerous, and so they're going to make sure that they don't fall off of it. But they get so focused on that cliff that they forget that there's also a cliff on the other side.
So in that sense, the advice is good and necessary. But it's kind of not, because the kind of person who needs the advice isn't often the kind of person who reads such a book.
I would argue that "the people who need to read this book" will read it and then announce, yes, of course, that's exactly how I do things. Perhaps that's why it's so popular. Everybody can see themselves in it.
I'll agree with your summary, but I'll also argue that moderation is often a lesson coders need to learn/remember. It is easy to "know" in theory but become dogmatic in practice. There are reasons we are still learning the lessons from 30+ years ago - we keep getting dogmatic about concepts that interfere.
I think GP's point is that saying "you need to do X, Y, Z" in moderation" carries nearly zero bits of information. Of course I don't want to overdo or underdo something. But how much is too much? How much is too little? How do I know? And since code is something that accumulates over time, how do I maintain the balance?
Answers to these questions is what's needed for coders to do a good job. The original book does encourage you to think about it, but doesn't provide many answers. The way I remember it, it was very useful at introducing you to concepts, so that you know that X, Y and Z are a thing in the first place.
You’re lucky it’s intuitive for you. I think it’s valuable to have credible sources backing up my intuition because I’ve worked in orgs that document way too much and way too little. So just calling out a desire for just right documentation (with copious examples) is handy to me so that people don’t idealize no doc systems or spend half their time documenting.
I think the complaint wasn't that the book was intuitive or not, but that it lacks actionable guidance. "Make sure to write the correct amount of documentation in a clear manner." sounds great on the surface, but doesn't actually help someone who is trying to figure out what the "correct amount of documentation" or "clear manner" actually is.
Agreed, the book is hit or miss in this regard. My take on actionable guidance ..
Step 1: choose a metric that makes sense.
Step 2: set a target for the metric.
Step 3: iterate until you hit the target.
So for "good, clear documentation" the right metric might be "other people using the documentation to do things and/or demonstrate they've learned something."
The target might be set a quiz or asking people to use the documentation to do something, and get a 80% passing rate.
The truly pragmatic thing is to not insist on getting anything right thr first time, to measure by outcomes not outputs, and especially to value the input of other people and be empathetic to your users, fellow developers, bosses and yes, even yourself (no failures, just data...)
I would counter that there value to spending time thinking about doing things in moderation, especially for those who think they do, but don't. It's a chance to shift their internal thought process such that they are a little more likely to think about that while doing their work, because they are now more familiar with it in a (second-hand) experiential sense. This is damn hard to quantify in terms of value, but it definitely greater than zero IMO.
Because software is largely based on intuitive understanding due to its largely creative nature.
The other side of the coin is that people are constantly reinventing the wheel, bloating the tool sets, and relearning lessons already learned because of lack of standardization.
but that's the entire point. Almost all of programming is walking a line between awful and over-engineered. There's sweet spots that one has to find in every part of the software delivery process.
The way to resolve the dispute (should there not be much difference between them) is to arbitrarily pick one and iterate in short bursts to ensure its assertions come good.
Might be brutally simply and obvious but still too many people manage to not achieve it. Appreciate a practical framework for how to measure too simply vs too complicated might be helpful, but often I suspect teams aren't remotely interested in a "let's not overcomplicate this" influence.
>Not much here would be useful in resolving a dispute between two programmers, one who wants to do things one way and one who wants to do it a different way.
This is probably not what you meant, but: The last thing I want in those types of discussions is "But book X says this!"
Sadly true of far too many "influential" books. Although I did enjoy reading it, I finished it in an afternoon - if that's possible, it's probably not hiding any real deep wisdom.
I haven't read the book, but I have to challenge the assumption here. That you didn't get anything out of it in an afternoon's sprint through it does not make it "probable" that it's not hiding any deep wisdom. It could mean that, or it could mean that you didn't stop to digest what it was actually saying.
