Comment

Comment by masto

I don't want to get sucked into defending Google-style design docs (I have.. opinions), but on this particular point a couple of things come to mind:

1. Presumably you've written the doc to be read by other people. What's obvious to you might not be obvious to them.

2. If you have no "alternatives considered", it's an indicator that you didn't consider any alternatives. I can think of times when "this is obvious and it's the way we've always done it" sent me down the wrong path. Spending just a couple of minutes considering whether obvious == correct, and writing down why, is not a bad investment in the long term.

3. I can only speak for myself, but I don't enjoy being criticized and I don't enjoy being wrong. "Alternatives Considered" is often at the end of the doc and I'm tempted to avoid it because there's a very real possibility that I will find the process of explaining why we don't just do option B instead leads to a realization that option B is a better alternative than the plan I just spent all that time on.

9/10 times it's short and easy, but it's still a worthwhile exercise for the reasons above. Explaining the "don't do anything" alternative is a good way to reinforce the cost/benefit of what you're proposing, and it's usually pretty easy to put yourself in someone else's shoes for a second and think of the first "but why don't you just" that will probably pop into their head. Write down "because it won't scale" and you've saved yourself that conversation. (joking. maybe.)

parent masto 2 years ago

Discussion

Live from the official Hacker News API

A modern reader for Hacker News · SvelteKit + Skeleton