Once you accept that unfinished work should be shown to a reader early, a practical question follows: how, exactly? A written note, a live walkthrough and a draft pull request all work, but they work in different ways. This comparison looks at three common formats for early review of DevOps work, such as a pipeline change, a design sketch or a runbook outline, and says when each one is the right choice. The point is the same throughout: catch the big misunderstanding while changing course is cheap.
The three formats at a glance
For a typical piece of infrastructure or delivery work, teams reach for one of these:
- A written draft with a short ask, sent as a message or a comment on a document.
- A live walkthrough, where you share a screen for fifteen minutes and talk through the sketch.
- A draft pull request, where the code is opened early and marked as unfinished.
None of them is universally better. The right choice depends on what kind of feedback you need, how many readers there are and how far the work has gone.
Format one: the written draft with a short ask
This is the lightest option. You write a half page: the problem, your intended approach, the three assumptions you are least sure of and the single question you want answered. The reader responds when they have time.
Strengths: It costs the reader little and leaves a record. It forces you to put your thinking into words, which often exposes gaps before anyone replies. It suits readers in other time zones and works well when only one or two people need to see it.
Weaknesses: Replies can be slow or shallow. A reader who skims may miss the point, and tone is easy to misread. There is no chance to notice confusion on someone’s face.
Best for: early direction questions, such as whether an approach suits the team’s constraints, when no code exists yet.
Format two: the live walkthrough
Here you gather a reader or two for a short call and talk the sketch through while they interrupt. A fifteen-minute slot is enough for most early drafts.
Strengths: It is the fastest way to uncover a misunderstanding, because the reader can say “wait, what does that box do?” the moment it occurs to them. You see hesitation directly, and follow-up questions get answered on the spot.
Weaknesses: It needs two calendars to line up. It also leaves no record unless someone takes notes, and there is a risk that you explain too much, filling gaps that the written draft would have exposed. Louder voices can steer the conversation.
Best for: work with a tricky shape, such as a deployment flow that crosses several teams, where seeing a reader’s reaction is worth more than a thoughtful written reply.
Format three: the draft pull request
You open the change early, mark it as a draft and describe what you want reviewed. The code is partial and may not pass every check yet.
Strengths: The reader sees real material rather than a description of it. Comments attach to specific lines, and the history shows how the work changed. It suits engineers who already live in the code host.
Weaknesses: Code draws attention to detail. Readers start commenting on style and naming rather than on whether the approach is right, unless you are firm about scope. It is also unsuited to non-engineers, who may never open the tool.
Best for: work where the approach is mostly settled and you want a look at structure or risk before investing in tests and polish.
A side-by-side summary
- Speed of response: live walkthrough first, draft pull request second, written note last.
- Depth of reaction: walkthrough and written note both do well on direction; pull request does well on line-level detail.
- Record left behind: pull request and written note keep a trail; a walkthrough does not unless you write it up.
- Readers outside engineering: written note or walkthrough only.
- Effort to prepare: written note is modest, pull request depends on the code, walkthrough is small if you already have a sketch.
Whichever you choose, state the ask
The format matters less than the framing. In every case, tell the reader what kind of feedback you want and what to ignore. “I only want to know whether this rollback plan makes sense; please skip naming and formatting” works in a message, on a call or in a pull request description. Without it, the same draft attracts scattered comments, and you leave the review no wiser about the thing you were worried about.
The matching move is to combine formats. A common pattern is a written note for direction, then a short walkthrough if the reader seems unsure, then a draft pull request once the approach has been agreed. Each step narrows the question, and none requires polish.
One piece of work, three routes
Take a concrete case: a draft rollback procedure for a service that is updated every week. Sent as a written note, it would carry the steps, the trigger for rolling back and a question such as “is this trigger too eager?” A reader might answer that evening, perhaps with one useful remark and one misunderstanding that never gets cleared up. Walked through live, the same draft would probably surface the misunderstanding within a minute, since the reader would stop at the unclear step. As a draft pull request, the procedure would live in a script, and comments would land on particular lines, but someone would likely suggest a nicer variable name before anyone questioned the trigger.
None of these results is wrong. They simply emphasise different things, which is why it pays to decide in advance what you need. If your worry is the trigger, the walkthrough wins. If you need a trail for an audit later, the written note wins. If the steps are nearly final, the pull request wins.
Slips that spoil every format
- Sending the draft with no question attached, so replies scatter.
- Choosing too many readers, which produces conflicting notes.
- Defending the draft during the review instead of listening.
- Collecting comments and changing nothing, which teaches readers not to bother.
- Waiting until the work looks respectable before showing anyone.
Each of these is avoidable with a little discipline, and each costs more the later it occurs.
Comparing it to planning in other settings
The same choice of channel appears wherever people plan together. Take KeralaOrbit, a Kerala events site: it keeps events apart from venues, and both apart from the forum and the blog, so the analogy to choosing between a note, a conversation and a longer write-up is easy to see. Choosing the right channel for the question is half the work of getting a useful answer.
Matching format to the culture around you
Teams with strong written habits find notes natural, while teams that talk a lot may prefer walkthroughs. A change in how people share unfinished work is partly a change in culture, which is why the guide on managing cultural change when adopting DevOps is worth reading alongside this one. And because early review is also a risk-reduction habit, the article on managing risk for reliable and secure delivery covers the wider picture of catching trouble sooner.
Timing and frequency
How often you ask matters nearly as much as the format. One early review at the sketch stage and one more at the half-way point is plenty for most tasks. More than that and readers tire; fewer and the benefit shrinks. Put the first request in your plan, near the start, so that it happens by default and not only when you feel confident. Keep each round short, and let the reader know up front that you are asking for a quick reaction instead of a full read, which makes it easier for them to say yes.
A simple decision rule
If you are unsure which format to use, ask yourself two things. First, is there code yet? If not, start with a written note. Second, how large is the risk of a misunderstanding? If it is high, such as work that touches several teams, pay for a short walkthrough. If the approach is agreed and you want reassurance before finishing, open a draft pull request. When in doubt, pick the lightest option that can still answer your question, and escalate only if the reply is unclear.
Whichever route you take, resist the temptation to wait for a better moment. The cheapest feedback is the kind that arrives before the work looks impressive.









