I worked at Amazon and their design doc culture was amazing. My next job was at a place that (I think) borrowed their engineering culture from Google (or maybe the ambient startup culture of SF?) and their design doc process was a pointless joke.
They are one mechanism that fits in a broader working culture. If you’re working solo, it’s an extravagant exercise. If you’re in a huge team, it’ll enable leveraging more expertise across the team and act as documentation.
There are a few different failure modes.
* Valuing output not outcomes is classic misalignment. (writing 40 page docs for promo — this doesn’t work except for very junior folks who are proving the ability to string words together more than deep eng)
* As mentioned, it’s a bit much of solo teams. Other small teams can comfortably communicate through issues (Jira) plus breakout sessions to hash out ideas.
* Engineers also need to be onboarded to effective design doc writing. (note a top commenter frustrated that their first effort isn’t immediately met with adulation, a possible flag.)
Writing about code is hard. Usually this is an exercise celebrated on HN. If you’re in a team, beware if you find your work is always that which doesn’t need to be explained and deeply considered in a shareable doc.
(disclaimer: very org dependent, as all statements about Amazon are.)