Design Doc Coaching: How Senior Engineers Get Architecture Approved

A good design doc does not win because it is long. It wins because it makes a technical decision easier to understand, challenge, approve, and execute.

Design doc coaching is useful when your architecture ideas are solid, but reviews become slow, political, or confusing.

What a design doc is really for

A design doc is not documentation after the fact. It is a decision tool.

It should help readers understand:

• what problem is being solved
• why the problem matters now
• what options were considered
• what trade-offs are being accepted
• what risks remain
• how the rollout will happen
• how success will be measured

If readers cannot answer those questions quickly, the doc is probably doing too much or too little.

The common design doc mistake

Many engineers write from the inside out.

They start with implementation details, service names, classes, database tables, and diagrams. Those details matter, but they are not the first thing reviewers need.

Start outside in:

1. Problem
2. Constraints
3. Goals and non-goals
4. Options
5. Recommended approach
6. Risks
7. Rollout
8. Open questions

This structure lets people debate the decision before getting lost in mechanics.

Make trade-offs explicit

Architecture reviews become frustrating when trade-offs are hidden.

Strong design docs say things like:

• This improves delivery speed but increases operational ownership.
• This avoids a migration now but keeps the data model harder to evolve.
• This option is simpler for one team but creates coupling for another.
• This design is not the most scalable option, but it is enough for the next twelve months.

That honesty builds trust. Staff-level engineers are not expected to find perfect designs. They are expected to make the cost of each choice clear.

Write for the skeptical reader

Assume one reader is worried about reliability, another about delivery time, another about product flexibility, and another about operational load.

Address those concerns directly:

• What can fail?
• How will we detect it?
• How do we roll back?
• What happens if traffic doubles?
• What happens if the product direction changes?
• Which team owns this after launch?

This reduces back-and-forth and shows mature technical judgment.

Use diagrams carefully

Diagrams should simplify the decision, not decorate the document.

Useful diagrams show:

• boundaries between systems
• data flow
• ownership
• synchronous vs asynchronous communication
• migration phases
• failure points

Avoid diagrams that require a meeting to explain. If the diagram is necessary, label it clearly enough that a reviewer can understand the main idea alone.

Coaching questions for your next design doc

Before sending the doc, ask:

1. Can someone understand the problem in the first two minutes?
2. Are the goals and non-goals clear?
3. Did I compare real alternatives?
4. Did I explain why the recommended option is best?
5. Are the risks and rollback plan visible?
6. Is the ask clear: review, approve, decide, or comment?

If the answer to any question is no, revise before requesting review.

Strong design docs are one of the clearest signals of technical leadership and Staff Engineer readiness.