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.
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.