Getting Feedback on Designs
Publishing a design doc and waiting for comments is the least effective way to get feedback. The best feedback comes from a deliberate process: pre-socializing key ideas, choosing the right reviewers, making it easy for people to engage, and handling disagreements constructively. The document is the centerpiece, but the conversations around it are where the real design work happens.
A design doc with no comments is not a sign of a great design. It is a sign that nobody read it, nobody cared, or nobody felt safe disagreeing.
Pre-Socialization
The biggest mistake in design reviews: publishing a fully formed proposal to a broad audience with no warning. This creates two problems. First, reviewers feel ambushed — they are seeing complex ideas for the first time and are expected to respond thoughtfully under time pressure. Second, the author has invested significant effort in the current approach and is psychologically anchored to it, making them defensive about feedback.
Pre-socialization fixes both problems. Before publishing the design doc, talk to the key stakeholders individually. Share your rough thinking. Ask for their concerns. Incorporate their input into the draft.
Pre-socialization timeline for a major design:
Week -2: Informal conversations with 2-3 key stakeholders.
"I'm thinking about approaching the caching problem
this way. What am I missing?"
Week -1: Share a rough draft with 1-2 trusted reviewers.
"Can you poke holes in this? I want to find the
weaknesses before the full review."
Week 0: Publish the design doc to the full review group.
Key stakeholders have already shaped the proposal.
The doc addresses their concerns. The review focuses
on refinement rather than fundamental objections.
Pre-socialization is not about building consensus in advance or manipulating the review. It is about producing a better document by incorporating diverse perspectives early. It also builds buy-in: people who contributed to the design feel ownership over it. A reviewer who sees their suggestion reflected in the doc is an ally, not an adversary.
For smaller designs, pre-socialization can be as simple as a five-minute conversation: "Hey, I'm writing up a design for X. My current thinking is Y. Does that seem reasonable, or am I missing something?" That five minutes can save days of review cycles.
Choosing Reviewers
Not all reviewers serve the same function. A good review group includes different perspectives:
Reviewer types:
Domain expert: Someone who knows the problem space deeply.
They catch incorrect assumptions and missing requirements.
System expert: Someone who knows the systems your design
interacts with. They catch integration issues and
operational risks.
Skeptic: Someone who will challenge your approach and push
back on hand-waving. They make the design more rigorous.
Newcomer: Someone relatively new to the area. They catch
unclear explanations and missing context. If they can
follow the doc, it is well-written.
Stakeholder: Someone affected by the outcome — a team
that will consume your API, an ops team that will run
your service, a product owner with requirements.
Three to five reviewers is the sweet spot for most designs. Fewer than three risks groupthink. More than seven leads to diffuse responsibility where everyone assumes someone else will do the thorough review.
Explicitly name your reviewers when you publish the doc. "I'd appreciate reviews from Alice (database expertise), Bob (payments domain), and Carol (ops perspective)" is far more effective than "please review" sent to a mailing list. Named reviewers feel personal responsibility. Unnamed reviewers assume someone else will handle it.
Set a review deadline. "Please provide feedback by Friday EOD" creates urgency and sets expectations. Open-ended review requests languish. A week is reasonable for most designs. Two weeks for large, complex proposals.
Making Feedback Easy
The easier you make it to provide feedback, the more and better feedback you will get. Several practices help:
Ask specific questions. Do not just publish the doc and ask "thoughts?" Instead, direct reviewers to the areas where you most need input.
Vague: "Please review and let me know your thoughts."
Specific: "I'd especially appreciate feedback on:
1. Is the cache invalidation strategy in section 3.2 sound,
or will we hit consistency issues I haven't considered?
2. The alternatives section proposes sharding as an option
but rejects it — do you agree with that assessment?
3. Is the 5-week timeline realistic given the team's current
commitments?"
Specific questions lower the barrier to engagement. A reviewer who does not have time for a full review can still answer one targeted question. Specific questions also signal where you are least confident, which focuses reviewer attention on the areas that need it most.
Structure the doc for partial review. Not every reviewer needs to read every section. Label sections by intended audience when appropriate.
"Section 3 (Detailed Design) is the primary section for
technical review. Section 5 (Timeline) needs validation
from the engineering manager. Section 4 (Alternatives) would
benefit from input from the database team."
Respond to comments promptly. If a reviewer takes the time to provide feedback and gets no response for a week, they will not review your next design doc. Acknowledge comments quickly, even if your full response takes longer. "Good point — I need to think about this" is better than silence.
Keep a running changelog. When you update the doc based on feedback, note what changed and why. Reviewers who provided feedback want to see that it was considered. Reviewers who read the doc later need to know which version they are looking at.
## Changelog
- v2 (April 10): Updated cache TTL from 300s to 60s based on
Carol's feedback about consistency requirements.
- v2 (April 10): Added Redis Cluster failure scenario to risks
section per Bob's comment.
- v1 (April 7): Initial draft published for review.
Handling Objections
Feedback on design docs ranges from typo fixes to fundamental disagreements about the approach. How you handle each type matters.
Minor feedback
Typos, formatting, unclear wording. Accept these graciously and fix them immediately. Do not argue about whether a sentence was "clear enough." If someone misunderstood it, it was not clear enough.
Clarification requests
"I don't understand how X works" or "What happens in case Y?" These are gold. They reveal gaps in your document or your thinking. If the answer is in the doc, improve the doc so the next reader finds it. If the answer is not in the doc, either add it or explain why it is out of scope.
Technical challenges
"I think approach X would not work because of Y." These require serious engagement. Do not dismiss technical objections defensively. Evaluate them honestly.
Defensive response (avoid):
"I already thought about that and it's not an issue."
Constructive response:
"Good point. Let me walk through why I think it's manageable:
[specific reasoning]. But I could be wrong — have you seen
this fail in practice? If so, I'd like to understand the
conditions."
If the objection is valid, update the design. If it is not, explain your reasoning clearly and let the reviewer decide whether they are satisfied. Document the discussion either way — future readers benefit from seeing the debate.
Fundamental disagreements
"I think the entire approach is wrong. We should do Z instead." These are the hardest to handle and the most valuable. Someone who disagrees fundamentally with your approach is either seeing something you missed or operating under different assumptions. Either way, you need to understand their perspective.
Steps for handling fundamental disagreement:
1. Understand the objection fully. Ask clarifying questions.
Do not respond until you can restate their position to
their satisfaction.
2. Identify the underlying assumptions. Often the disagreement
is not about the solution but about the problem definition,
the constraints, or the priorities.
3. Find the crux. What is the single point where you diverge?
Is it a factual disagreement (resolvable with data)? A
values disagreement (needs a decision-maker)? A prediction
disagreement (may need an experiment)?
4. Propose a resolution path. "Let's run a benchmark to settle
the performance question" or "Let's bring this to the tech
lead for a decision" or "Can we try approach Z for the
prototype and compare results?"
When to Incorporate Feedback vs. Hold Firm
Not all feedback should change your design. Some feedback reveals genuine issues. Some reflects different preferences. Some is wrong. Knowing the difference is a judgment call, but guidelines help:
Incorporate feedback when:
- The objection identifies a real technical flaw you had not considered
- Multiple reviewers raise the same concern independently
- The feedback comes from someone with direct domain expertise
- The change improves the design without significant cost
Hold firm when:
- The feedback is a style preference, not a technical concern
- You have already evaluated the alternative and have clear reasons for your choice (make sure those reasons are in the doc)
- The feedback would expand scope beyond the stated goals
- Incorporating the feedback would require fundamentally redesigning the solution and the reviewer has not articulated why that redesign is necessary
When you choose not to incorporate feedback, explain why. "Thanks for the suggestion. I considered this approach in the Alternatives section — the main reason I went with the current design is [specific reason]. Let me know if I'm missing something." This respects the reviewer's time and keeps the conversation constructive.
Never silently ignore feedback. Even a brief "Acknowledged, but I'm going to keep the current approach because [reason]" is better than no response. Silent rejection breeds resentment and discourages future reviewers.
Setting a Decision Deadline
Design reviews without a deadline expand to fill available time. Discussions continue indefinitely. New objections surface weeks after the initial review. The team never converges.
Set a decision deadline when you publish the doc:
"Review period: April 7-14. I'll address feedback through
April 14. Any unresolved disagreements will be escalated to
[tech lead / engineering manager] for a decision by April 16.
Implementation begins April 17."
The deadline creates urgency. Reviewers who care about the design will engage during the review period. It also creates a forcing function for unresolved disagreements — they must be escalated rather than left to fester.
After the deadline, document the decision:
## Decision Record
Decision: Proceed with proposed design (Redis caching approach).
Date: April 16, 2025.
Decided by: Alice (tech lead), after team discussion.
Key dissent: Bob preferred the sharding approach. His concerns
about cache invalidation complexity are mitigated by the
reconciliation job (section 3.4). Bob has agreed to disagree
and commit.
This record is valuable because it captures not just the decision but the reasoning and the dissent. Six months later, when someone asks "why didn't we shard?", the answer is documented.
The Document Is Not the Design
The design doc is a communication tool. The design itself is the set of decisions and trade-offs that the team agrees on. These decisions emerge from the conversation around the document — the comments, the hallway conversations, the whiteboard sessions, the Slack threads.
A design doc with perfect prose but no feedback produced a document, not a design. A rough doc that sparked a vigorous two-week discussion and produced clear decisions with documented reasoning — that produced a design.
This means the review process matters more than the document format. A team with a strong review culture and a mediocre template will produce better designs than a team with a perfect template and no review culture.
Common Pitfalls
Publishing without pre-socialization. Surprises breed resistance. Talk to key stakeholders before the formal review. Incorporate their input early.
Asking for feedback but not really wanting it. If you have already decided and the review is performative, people will notice. They will stop giving honest feedback on this doc and your future docs.
Taking all feedback personally. The design doc is not you. Criticism of the approach is not criticism of your competence. Separate your ego from the document.
Letting the loudest voice win. Not all feedback is equal. A well-reasoned objection from a quiet domain expert deserves more weight than a loud opinion from someone unfamiliar with the constraints. Evaluate feedback on its merits, not its volume.
Never closing the review. At some point, you must decide and move forward. Endless review is not thoroughness — it is indecision. Set a deadline, address the feedback, escalate if needed, and start building.
Not recording the decision. After the review, document what was decided and why. Without this record, the same debates resurface months later when new team members join or memories fade.
Key Takeaways
- Pre-socialize key ideas with stakeholders before publishing. The best design docs incorporate feedback from the start, not just during formal review.
- Choose reviewers deliberately: domain experts, system experts, skeptics, newcomers, and stakeholders. Three to five reviewers is the sweet spot.
- Ask specific questions to focus reviewer attention on the areas where you most need input.
- Handle objections constructively: understand the concern fully before responding, identify the underlying assumptions, and propose a resolution path.
- Set a decision deadline. Open-ended reviews expand indefinitely. Document the final decision, including dissent.
- The document is not the design. The conversations, decisions, and shared understanding that emerge from the review process are the real deliverables.