3 ms·
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
by 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 agoI 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 agoAgreed, 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...)