4 ms·

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 do

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.

TeMPOraL 7y ago
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.
- prepend 7y ago
  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.
  - diminoten 7y ago
    The people who say, "This is all obvious" are often the people who understand the "obvious" the least.
  - Goronmon 7y ago
    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.
    - Bjartr 7y ago
      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.
    - kthejoker2 7y ago
      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...)

TeMPOraL 7y ago

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.

prepend 7y ago
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.
- diminoten 7y ago
  The people who say, "This is all obvious" are often the people who understand the "obvious" the least.
- Goronmon 7y ago
  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.
  - Bjartr 7y ago
    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.
  - kthejoker2 7y ago
    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...)