Does it work? Is it better than alternatives? Where's that discussion?
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.
Design docs are vehicles for discussion. The idea is that they are the most efficient way to communicate your intention, motivation, why not alternatives.
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.
What makes them valuable or not valuable is how people respond to them. If it is all done as a "ritual" then it is stupid. If it is done because the org is legitimately critical about how it makes decisions and prioritizes resources, then it is valuable.
How intellectually serious it was. The treatment of docs was an extension of how they treated engineering in general, which was, seriously and critically. For the most part good engineering took precedence over politics and promotion material and shiny new stuff, unlike what it sounds like you get at a lot of companies.
(disclaimer: very org dependent, as all statements about Amazon are.)
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.