To Get Better Feedback, Show Your Work
"We'll route by tenant through the API gateway. We'll validate the token up front, then call billing early to pre-authorize before fulfillment. Fulfillment triggers off an event. Keeps it clean."
You walk through the design on a call. The flow makes sense in your head. A few people nod. No one pushes back.
But the next day, a teammate diagrams it out, and the problems start to surface.
- Billing blocks on a token that isn't always available
- Fulfillment depends on product data that wasn't included in the request
- An event fires before anything is committed, so rollback is unreliable
The design fell apart because no one could see it clearly enough to question it.
That's what happens when you skip the context. Without a diagram, a review doc, or something concrete to react to, the team is stuck trying to imagine the gaps. And when people can't see the gaps, they don't fill them. They just move on.
More Concrete Less Conceptual
It's impossible to give feedback on something you can't visualize.
Ask a room of software engineers, "Any thoughts on the architecture?" and you'll usually get a few vague ideas or polite silence.
Now, show them a rough diagram, a one-pager with tradeoffs, or even a stubbed-out interface, and the conversation changes. They react. They ask sharper questions. They point out edge cases you missed.
Concrete drafts give your team enough context to engage. They lower the barrier to providing feedback and make it easier for everyone to see what is actually being proposed. That's how you move from passive agreement to real alignment.
|
|
Wondering If a Startup Is Right for You?
Big Creek Growth Company shares what it’s really like to work in a startup and what founders are looking for when hiring.
|
|
This is also how you surface risk early. A decision made in conversation might feel settled, but without something visible to stress-test it, blind spots stay hidden.
In the 2023 Atlassian developer survey, 41% of engineers said poor documentation slowed their work, second only to tech debt.
That number is a direct reflection of how often teams are asked to deliver without enough shared understanding.
If you want honest feedback, don't ask for it. Show something people can respond to.
Start with Something the Team Can React To
Getting feedback is easier when people can see what you're thinking.
That might be:
- A pull request with a short explanation of the tradeoffs
- A one-pager that outlines the problem, constraints, and two or three options
- A whiteboard photo that maps how data flows through the system
- A Loom walkthrough of a rough prototype or sequence diagram
- A stubbed-out API interface with placeholder methods and comments
None of these need to be perfect. They just need to give the team enough structure to ask good questions.
This kind of context makes it easier to spot edge cases, resolve disagreements early, and build shared confidence in the direction.
This is the same principle behind the idea of Completed Staff Work—you're not handing off a half-formed idea. You're doing the work to make it reviewable and actionable.
Choose the Right Context for the Conversation
Not every idea needs a heavy multi-page document. The goal is always to provide just enough context.
Here are a few common scenarios where you should be adding context:
Making a small config or process change
Open a pull request and include a short explanation in the description. Call out what changed, why, and any downstream effects.
Shaping a sprint goal or sharing early thinking
Post a few clear bullets in Slack or Confluence. If it helps, record a Loom to walk through your rough outline and provide a link to any supporting materials.
Suggesting a new internal tool or pattern
Use a one-pager to define the problem, outline two or three viable options, and recommend a clear path forward. Focus on tradeoffs and constraints.
Proposing a new backend service or major integration
Share a short design doc or Architecture Decision Record (ADR) with the service boundary, responsibilities, and how it fits into the broader system. Add a domain diagram if it clarifies the flow.
Each of these provides your team with a starting point to work off of. A clear artifact makes it easier for others to ask questions, challenge assumptions, and advance the conversation.
If you're trying to move an idea forward, it's not enough to ask for opinions or schedule a meeting. You have to create the conditions for others to weigh in.
That means doing the work to make your thinking visible—whether that's a sketch, a short writeup, or a rough plan. When people have something concrete to react to, they can bring their perspective. And when you start from a shared context, it's much easier to reach a shared understanding.
If you're stuck waiting for alignment, step back and ask whether you've given the team enough to work with.