[fdsfsaa]

I don't think any specific type of change should require a design document. That framing presupposes too much hierarchy. Design documents, like code reviews and tests, ought to be helpful tools for developers, not requirements imposed from above. I've worked at companies that didn't require design documents, but occasionally wrote them anyway because I wanted feedback.

Another trigger could be a reviewer commenting, "Hey, this diff stack is getting pretty tangled. Can you write something that describes how it all fits together?"

You should trust your developers' judgement.

[zardeh]

(to be clear, this is all made up)

Well let's put it this way, let's say that I'm a googler, I work on the android team and I want to rewrite the launcher from the ground up because I have some whiz-bang idea. This falls under my general purview of stuff that my team works on, so I grab my coworker, and for a month we hack away at it and have a good MVP. It has great improvements over the existing homescreen.

We've been working and reviewing each other's code, and so after a month we submit the big change that touches bunches of files out for review by all of the various owners of various affected components. One of them shoots me an email a few minutes later and says that this work is all wasted because another team has been secretly working on an updated launcher for the release of Google's new flagship phone, the Pixel, it already has some of our features, but also has many others, and has been in development for 6 months already.

So now my coworker and I have wasted 2 man-months of employee time on something. That's tens of thousands of dollars that goes poof when someone closes the pull request. And those 10s of thousands of dollars could have been saved with a 2 page document and a 1 hour meeting.

The goal of these things is to not waste developer time, because you or I can't be aware of everything going on in a company, so writing a design doc allows other people to see what you're doing and

1. provide insight and feedback from their experience with similar problems

2. provide prior art from within the company

3. remind you of things you might have forgotten about

4. give you insight into how these changes will affect others

5. most importantly, give you information about other activities the company is doing in this direction that are related to your proposal, so that if you can avoid destructive interference, and potentially have constructive interference.

Otherwise you end up with repeated work, wasted effort, and fragmentation.

[tigershark]

This has absolutely nothing to do with design documents. As a developer you are not supposed to start working on whatever you like, you need to follow the big plan. Is it really like this in google with developers wasting their time just writing design documents on whatever they like that will obviously be rejected rather than doing the work that is expected from them? I don't think this is very productive with people working on a whim instead of following a plan in a coordinate way.

[zardeh]

You're exactly correct. Outside of 20% time, I can't see that example being really realistic (at least not at Google for an android launcher, there are other companies where I've heard of 10+ competing internal libraries for the same problem developed by different teams).

In the case that you're asked to implement a project from 'above', they're still useful, for practically the same set of reasons (maybe minus #5, but plus 'other people who you impact can provide feedback to reduce future friction')

[fdsfsaa]

Coordination is important. I think you can achieve it without a formal design document and approval process. Your team could post a quick, informal message to a mailing list saying that you're going to work on a new launcher. The other launcher team could then reply and suggest getting together to talk about common plans and avoiding duplicate work.

I'm not suggesting that communication is bad. I'm objecting strenuously (perhaps stridently) to the design document as a step in a rigid process and a requirement imposed from above.

Personally, I'd rather see two teams work toward our improved hypothetical launcher than to see zero teams do that work because process imposed too high an "activation energy" on the launcher experiment.

Also, why are both teams working in isolation for a month? If both teams check in code, the checkins themselves can provide an indication that other people are working in the same area. Incidentally, it's this effect that makes me strongly dislike feature branches. It's better to develop unstable code behind a feature flag, where the code is visible even if not active, than in a feature branch, where nobody can see it.

(It's true that not all changes can be gated behind a flag, but most can be.)

[zardeh]

>Also, why are both teams working in isolation for a month? If both teams check in code, the checkins themselves can provide an indication that other people are working in the same area. Incidentally, it's this effect that makes me strongly dislike feature branches. It's better to develop unstable code behind a feature flag, where the code is visible even if not active, than in a feature branch, where nobody can see it.

I chose my example carefully, the 'new' launcher being developed officially was part of a new, unannounced product, and therefore likely secret prior to release. On the other hand, the new version developed by the two people was a top to bottom revamp, which might mean an entirely new application, or something that can't easily be done behind a feature branch.

>Personally, I'd rather see two teams work toward our improved hypothetical launcher than to see zero teams do that work because process imposed too high an "activation energy" on the launcher experiment.

And again, I chose my example carefully: one team would always have created this new launcher, it was creating something as part of a much larger initiative.

>I'm not suggesting that communication is bad. I'm objecting strenuously (perhaps stridently) to the design document as a step in a rigid process and a requirement imposed from above.

Indeed, but if nothing else, a design document is a formalized process for this type of communication. To be clear, my understanding is that Google also has best practices in place for objections and blockages to things proposed through design documents.

The result is that when you are planning to create a feature that is large enough that it is, shall we say, statistically likely to break things or cause someone else serious aggravation, there is, if you are following policy, a formalized process for informing the people who your change might impact, a way for them to provide feedback, and a formalized way to resolve conflicting opinions when each engineer thinks that their workflow or feature is the most important.

This goes back to the other example I gave, which was a real one, where my design documented project could have, if implemented, created a situation where, until rectified, breaking changes would have gone undected by automated tests, and instead shown themselves in the tests for unrelated changes, which would have been an annoying bug to track down, and would have caused some other team a lot of stress and time. They would never have been notified until final review, and conceivably could have been months of wasted effort on my part.

[fdsfsaa]

> secret

If your culture is one of secrecy (Google's generally is not), then you need process to effect coordination, since nothing else can. Fortunately, good (IMHO) software companies are internally open, so there's no secrecy forcing them into heavyweight process. Process is one of the many costs of secrecy.

> formalized process

The problem with formalized anything is that it involves writing down rules. When you write down rules, you have to distill complex and subtle human interactions into essentially an algorithm for people to follow. The loss of nuance, while creating clarity, introduces inefficiency, since it forces everyone to follow the same steps even when these steps are inappropriate.

You can't write down exceptions for all the inappropriate cases (but you can for some of them). If you tried to allow for a large number of exceptions, the resulting algorithm would be too complex to follow or it would be vague enough to allow anyone to skirt the rules.

I prefer to avoid formal rulesets for human processes. In my experience, the efficiency loss arising from formal rulemaking has outweighed the gain in clarity. Maybe others have different experiences, but in mine, the higher the quality of developer you have in an organization, the fewer formal rules you need.

Applying lots of formal rules to good developers just makes them unhappy.

[zardeh]

> internally open,

Internally open does not mean that everyone can always see everything though.

>Applying lots of formal rules to good developers just makes them unhappy.

I'm not sure I agree with this. I'm a developer, and I'm happier when there are formal rules about human code review, code style, automated testing, and minimal test coverage.

I'm happy about those things because they are a small inconvenience (if one at all) that save me time and effort down the line, and insulate me from lazyness, and mistakes on the part of developers (myself included!).

I see design documents as an extension of this. My pay in is that I occasionally need to write a document outlining my thought process w.r.t. a new (large-ish) feature I'm implementing. In exchange for this, I know that I will not waste my time reinventing things and, more importantly, when other people intend to make changes that will potentially negatively impact me, I will be able to provide feedback before those changes go live.

[fdsfsaa]

> Internally open does not mean that everyone can always see everything though.

If secrecy is rare in an organization, secrecy-induced problems in that organization are also rare.

> I'm not sure I agree with this. I'm a developer, and I'm happier when there are formal rules about human code review, code style, automated testing, and minimal test coverage.

It takes all kinds, I guess. Personally, nothing galls me more than having to follow a rigid set of rules when I know the original motivation for these rules doesn't apply to my situation. I'd make a terrible soldier.

I understand your social contract argument, but IME, the benefit to me of other people writing design documents isn't big enough to justify my having to do it. I find that subscribing to actual code reviews targeting directories that interest me gives me enough ability to see and affect (and unfortunately, sometimes block or delay) changes before they go live.

[acjohnson55]

While I agree with you in principle, I have my doubts that that approach works at "Google scale".

[fdsfsaa]

What makes "Google scale" unique? I've never understood the argument that because Google serves ultraziggabytes of data, Google needs complex engineering practices. A program is the same program whether it runs on ten machines or ten thousand. Complexity is what matters, and while Google does solve very complex problems, other companies solve them too.

[zardeh]

I think the point is that every company that works at this scale does more or less the same thing out of necessity.

[fdsfsaa]

Saying that process is a necessary side effect of growth is like saying cancer is a necessary side effect of age.

I don't think you have the causation quite right --- it's not necessity that forces the adoption of process exactly. Process is what you get by default if you don't consciously counteract natural human tendencies in management. A lot of large companies stop consciously protecting their culture, so they get the default big company culture instead. The default big company culture is ever-increasing process.

[kuschku]

Do they? Not even governments do that – instead, they manage billions of people and trillions of dollar by having a hierarchical structure, instead of using a long legislative process for every decision.

[zardeh]

Why do you think those two things are impossible to do at the same time. Most companies also have hierarchical structures, and most governments use some kind of bureaucratic process to approve major new projects, I'd expect it to be more bureaucratic than at most businesses.

[kuschku]

But that’s even not the case, that’s the point. Most governments let their government agencies just do things, without unreasonable bureaucracies like these.