I feel like at Google, design docs suffer from being the main thing that goes in your promo packet, which leads to the writing being done more with promo committee in mind then the documents ostensible audience of people who are working on the system the document pertains to.
True for every employer i've ever been at. Your career is mostly steered by exposure, rather than reputation or ability. Design docs are very visible to those above you. At yvery company I join, I propose we start writing design docs. It immediately puts me in good standing with management :)
This makes many docs follow the pattern of a more complex design when its completely unnecessary. All just to get more "perf points" from the people that only have time to skim through the docs.
I read many docs that, to me, obviously made up a decision and showcased the thing we already wanted by the time the doc was started, and 2+ silly alternatives (at least one way too simple and an unnecessary overkill) and contrasted them to pick the thing that was reasonable.
Devs straight up tell you that they write design docs for the promo committee. That is their goal, everything else is secondary. Given that they never know which design docs they will use in their promo packet they put everything they work on in design docs no matter how small. There is the idea of a one pager design doc, but usually they grow from one page to ... many. It might be a one week project, but a design doc gets written. I have also had to reviewed 20, 30, even 40 page design docs that took clearly a while to make and at any other company would be simply a JIRA ticket. I have had discussions about how many pages is too many and if we should have a limit etc.
Too many have learned (correct or not) that promo committees want to see that only the author wrote a doc and no one else. This further slows down everything and disincentivizes cross learning. I know software engineers who spend a full quarter or more in isolation writing design docs. The majority of the writing in a design doc is the actual design, but the other 99% is the definition of the problem. Too many times I have been in a review and spent a bunch of time improving the definition of the problem which results in the design needing to be scrapped and most of the doc needing to be re-written.
Worst case scenario is when by improving the problem definition a simple solution appears that doesn't require a complex design. The author having invested a lot of time in a complex design (that historically and many committees still look for to promote off of) will push back against anything that is simple. The difficult trick is helping the engineers to improve their problem definition early in the writing process.
I have seen design docs that have no alternatives presented. The design doc was simply a labor intensive way to write down what needed to get done or what someone wanted to do.
This also results in design docs turning into a bug tracking system if you squint. In a hand wavy way everyone is working on their design doc, not bugs, bugs can't get you promoted.
And OP like to wax poetically about how when you join a team you can just go and look at the design doc like that is a simple and obvious thing. They are often not tracked in any central place. For many teams design docs are not owned by the team or the project, but by the individual because you can make sure no one else contributed. This is again for the promo committee sake. Many design docs you can't get access to, not because they are super secret, but just because. And it isn't like teams have say two or three design docs, no there is a mountain of design docs to read. And with around a two year turn over at Google many design docs get lost to time. At any other company this could be like if you joined the team and I said everything you need can be found by reading all the closed bugs or read every commit message in the main branch.
Anywhere else I would have been grabbed after lunch and would have worked on defining the problem for a few hours with the team at the whiteboard. The senior members teaching the younger in real time how to think about these things and iterating quickly. Most of the time this would be written down in the bug tracking system or for bigger stuff in the project's wiki/folder to be owned by all.
All of the above can be improved and I have worked on improving all of them, but culture is a slow thing to change. Design docs are a good idea as a concept, but there are pitfalls and the way they are being used by many (not all!) at Google is not it.
> Worst case scenario is when by improving the problem definition a simple solution appears that doesn't require a complex design. The author having invested a lot of time in a complex design (that historically and many committees still look for to promote off of) will push back against anything that is simple. The difficult trick is helping the engineers to improve their problem definition early in the writing process.
The worst case is really when even more time has been spent coding, testing, releasing, and integrating the overly complex design, and then it's extra work on top to get rid of it.
> Anywhere else I would have been grabbed after lunch and would have worked on defining the problem for a few hours with the team at the whiteboard.
I do that at Google regularly, often in parallel with writing the doc. Nothing beats talking with an experienced engineer directly.
I'm not sure what the difference is, except giving more context than teammates need, or trying to make a problem more complex than it is.
By and large I didn't notice that strategy working.
On the other hand, for context, people wrote large docs on what the team did and does, what the problems are, etc. and those did tend to be long and exaggerated.
