Design Docs at Google

> The main issue is that it does require good, empathetic management, long-term retention of experienced, capable people, and an "apprenticeship" model.

To me this sounds like an idealistic environment. I doubt this environment could fail with any sort of process (or lack thereof).

Documents don't have to be "incredibly detailed, formal, approved-by-everyone-including-the-mens-room-attendant". Those are probably the worst kind. I do think that OP's/Googles design docs does seem to lean towards that, unfortunately. I wonder if that's how it is in practice? Especially given the length -- 10 to 20 pages sounds like it's too detailed for me. Though I suppose on bigger projects the sum of all the implementations of the moving parts can get quite large.

One criticism I especially have of OP's "Review" section is they mention opening it up to a large audience. I am skeptical whether that is how it actually goes down. In my experience, opening something up to review by many people just ends up being a too-many-cooks situation. Pretty much what you're afraid of with "approved-by-everyone-including-the-mens-room-attendant". Those situations just turn into bikeshedding. In reality, I bet it gets opened up to everyone but only a couple people are actually expected to be the ones who give feedback on it.

I still think I'd take the over-formalized process over tribal knowledge. What you don't see behind the scenes of tribal knowledge are people with a lot of it who constantly get interrupted to answer those questions. It ends up being very inefficient at scale. Not to mention the overhead that comes with the person trying to answer the question -- like finding old breadcrumbs about the problem like code or emails. Along with the worst enemy of work for a developer: context switching. I've been the person with tribal knowledge and it basically becomes your full time job. It was great for job security but I lament the amount of time I lost because I wasn't more proactive about writing documentation.

Reproducibility is just a side effect of lack of specificity, which is the major difference and the entire point of my critique. Design docs don't tell you enough to actually build the thing you want to build.

Hah, design docs at Google...

I read probably hundreds of deigns docs during my 6 years at Google.

I think among them, only a handful of design docs, like The newer design docs, which are served as actual working documents for an active projects, are no doubt primarily a process mechanism to solicit design inputs, and garner supports from stakeholders.

It is a formality to show that the project owner is willing to waste his time and to convince so-called "reviewers" about the validity of the project. The reviewers usually do not read the design doc in earnest. Only the stakeholders, like the TL of the team, potential customers, partners, would spend serious time on them. It's more or less a debate ground for stakeholders to pointing fingers at the design process. That's also why the design doc is written in Google Doc in the first place.

Once a design is "approved", it usually means from most major share holders are satisfied, to everyone is wearied down enough and the project has enough importance to actually push forward, they are OKed for implementation.

After that the design doc is largely useless, the designs laid out in the doc is usually 1) too simple that there is no need to consult design doc anyway, one can explain it in a few minutes chat; 2) too complicated that the design diverges from the actual code that the design doc offers little guidance. And very few design docs sit in between.

All in all, anything produced during a software engineering project seems all is about being a tool for organizing the human interaction process, the artifact, aside from a very high-level motivational piece, and the end result code + docs, whatever in between seems largely bears little value after the work is done.

And frankly that's how most of the design docs at Google really are. They're post-facto descriptions put together for the purpose of gaining promotion.

Agreed. On the second point, it’s definitely a bit cultural thing of the group/org. Worth note that at the higher level of the Corp ladder, there’s indeed fewer work(with the wanted scope) then the people (that’s looking to do next level work)