6 ms·

We do "one-pagers" if there's basically one, simple, straight forward way to do something; however, I'm with google on this one. If you're designing something,

We do "one-pagers" if there's basically one, simple, straight forward way to do something; however, I'm with google on this one. If you're designing something, and there's only a single solution under consideration, either there's no design, or you're not being thorough. Choices and tradeoffs are what make design

wasteduniverse 2y ago
[dead]
mewpmewp2 2y ago
What if it is something really obvious and has been done so for last 20/20 times it feels almost embarrassing to consider anything else? You could list out the embarrassing methods, but it still feels useless work for show.
- Jensson 2y ago
  Then it is just a change and reviewed through normal code review. Design docs is only for when you do something that isn't obvious.
  - mewpmewp2 2y ago
    But then you don't get promo?
    - Arainach 2y ago
      You don't get promo in your scenario either. A design doc for something that's trivial will be called out in promo packet review and not given much credence. If the packet is primarily comprised of such artifacts the promo will be denied.
      - lupire 2y ago
        It depends on level. For a junior, these are great design docs because they educate other juniors about engineering, and educate senior bad-doccers about good doc writing, and show developing skill in the art of doc writing, before the engineer has the additional cognitive burden of writing about something much harder.
    - jppittma 2y ago
      Do good non-doc-worthy work => Get doc-worthy work => Write doc => Get promo
- masto 2y ago
  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.)
  - aatd86 2y ago
    > I can only speak for myself, but I don't enjoy being criticized and I don't enjoy being wrong. That's actually a huge problem because it can veer onto intellectual dishonesty and being combative for nothing. Instead, one should be trying to look for the right/best path forward, regardless of what they thought. Should be easy to discard erroneous ideas. The goal is not to be right. It's to find what's right.
    - goostavos 2y ago
      >The goal is not to be right. It's to find what's right. This is why I think design docs need to be lightweight and reviewed early. Design docs shouldn't be a masterpiece perfected in isolation over the course of days or weeks. That guarantees the author has calcified their opinions. When I was on review panels at Amazon, 99% of them were an exercise in futility -- the author had already poured concrete. It is very, very, very hard to avoid the mental trap of "Hrmph! I've thought about this more deeply than anyone else" that comes from living down in the isolated world of "doing design." The earlier you get other eyes involved, the more likely people will actually listen to feedback and consider alternatives. You still, of course, need that heads down time to put in all the details, but the overall shape of the design shouldn't be a big reveal when you hit the design review.
- burnished 2y ago
  Then it'll be easy and fast and really not embarrassing at all.
- eschneider 2y ago
  Hmm...most of the time when I do a design that's for something at all substantial, I'll usually go through a few ideas that seem reasonable at least through the "napkin stage" before dumping them in favor of what eventually becomes the "real design". I'd just save those napkins, list them in the alternatives section, and explain why they were abandoned. Easy.
  - jppittma 2y ago
    That’s the idea. I try set it up so the time I spend on the idea in the doc is proportional to its viability.

wasteduniverse 2y ago

[dead]

mewpmewp2 2y ago

What if it is something really obvious and has been done so for last 20/20 times it feels almost embarrassing to consider anything else? You could list out the embarrassing methods, but it still feels useless work for show.

Jensson 2y ago
Then it is just a change and reviewed through normal code review. Design docs is only for when you do something that isn't obvious.
- mewpmewp2 2y ago
  But then you don't get promo?
  - Arainach 2y ago
    You don't get promo in your scenario either. A design doc for something that's trivial will be called out in promo packet review and not given much credence. If the packet is primarily comprised of such artifacts the promo will be denied.
    - lupire 2y ago
      It depends on level. For a junior, these are great design docs because they educate other juniors about engineering, and educate senior bad-doccers about good doc writing, and show developing skill in the art of doc writing, before the engineer has the additional cognitive burden of writing about something much harder.
  - jppittma 2y ago
    Do good non-doc-worthy work => Get doc-worthy work => Write doc => Get promo
masto 2y ago
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.)
- aatd86 2y ago
  > I can only speak for myself, but I don't enjoy being criticized and I don't enjoy being wrong. That's actually a huge problem because it can veer onto intellectual dishonesty and being combative for nothing. Instead, one should be trying to look for the right/best path forward, regardless of what they thought. Should be easy to discard erroneous ideas. The goal is not to be right. It's to find what's right.
  - goostavos 2y ago
    >The goal is not to be right. It's to find what's right. This is why I think design docs need to be lightweight and reviewed early. Design docs shouldn't be a masterpiece perfected in isolation over the course of days or weeks. That guarantees the author has calcified their opinions. When I was on review panels at Amazon, 99% of them were an exercise in futility -- the author had already poured concrete. It is very, very, very hard to avoid the mental trap of "Hrmph! I've thought about this more deeply than anyone else" that comes from living down in the isolated world of "doing design." The earlier you get other eyes involved, the more likely people will actually listen to feedback and consider alternatives. You still, of course, need that heads down time to put in all the details, but the overall shape of the design shouldn't be a big reveal when you hit the design review.
burnished 2y ago
Then it'll be easy and fast and really not embarrassing at all.
eschneider 2y ago
Hmm...most of the time when I do a design that's for something at all substantial, I'll usually go through a few ideas that seem reasonable at least through the "napkin stage" before dumping them in favor of what eventually becomes the "real design". I'd just save those napkins, list them in the alternatives section, and explain why they were abandoned. Easy.
- jppittma 2y ago
  That’s the idea. I try set it up so the time I spend on the idea in the doc is proportional to its viability.