Velo Blog

Tag: notion

  • The manager doc, a one-page contract with your team

    The manager doc, a one-page contract with your team

    Every new manager at Velo writes a one-page document about how they work. We call it the manager doc. It lives in Notion, gets linked from the team’s home page, and each report reads it in their first week.

    We started doing this two years ago after a retro where three engineers said the same thing in different words: they could not predict what their manager wanted. One thought skip-level meetings were off-limits. Another assumed silence on a PR meant approval. A third had been sitting on a concern for six weeks because they were waiting for the right 1:1 slot. None of these were failures of intent. They were failures of shared context.

    The doc fixes that by making the invisible visible. Here is how we write it, what goes in it, and how we keep it from rotting.

    What goes in a manager doc

    We keep the doc to a single page. If it needs a scrollbar, something is wrong. The format is prose with short sections, not a bulleted resume. It reads like a letter to the team.

    We ask every manager to cover six things:

    • How I run 1:1s. Cadence, format, who owns the agenda, whether we take notes, where those notes live. One of our staff managers writes: “We meet Tuesdays at 2pm for 30 minutes. You own the agenda in our shared Notion page. I will always ask about one thing outside work. I take rough notes in the same doc.”
    • When to escalate to me, and when to go around me. This one is uncomfortable to write and the most useful to read. We name specific cases: a production incident on a service the team owns, a conflict with another team, a concern about a peer’s behavior, anything that touches compensation or headcount.
    • How I handle disagreements. What happens when a report thinks a decision is wrong. Do we debate in the 1:1, in Slack, in a written doc? What is the tie-breaker? Most of our managers land on some version of “disagree in the room, commit in the hallway,” but we ask them to say it in their own words.
    • How to give me feedback. Where, when, in what form. We ask managers to name a channel they will watch. One of our design managers wrote: “DM me on Slack or drop it in the feedback section of our 1:1 doc. I will not react in the moment. I will respond within 48 hours.”
    • What I care about beyond shipping. What good work looks like on this team. What behaviors get someone promoted. What gets a quiet conversation.
    • What I am bad at. This is the hardest section and the one that builds the most trust. Not false modesty. Real patterns. “I default to writing when I should be talking. Push back if I send you a wall of text instead of hopping on a call.”

    We do not prescribe a template beyond those six prompts. The voice matters. A doc that sounds like a policy manual gets ignored. A doc that sounds like the person gets reread.

    Keeping the doc alive

    A written statement is worth nothing if it drifts from reality. We tie the doc to the quarterly cycle.

    At the start of each quarter, every manager updates their doc and posts the diff in their team channel. Even a small change counts. Last quarter one of our platform managers updated exactly one line: her escalation policy for on-call incidents, after our Datadog paging rules changed. She still posted the diff. That signal matters more than the edit itself.

    We also run three checkpoints:

    1. New hire week one. The new report reads the doc, brings questions to their first 1:1. The manager updates the doc based on those questions. New eyes catch stale claims fast.
    2. Quarterly retro. During team retro, one prompt is: “Where did the manager doc match reality this quarter, and where did it not?” We surface the gaps in the room.
    3. Manager changes. When someone moves teams or gets a new manager, the incoming manager sends their doc within the first week. We treat this as non-negotiable.

    The docs live in a single Notion database with a last-updated column. Our head of engineering scans it monthly. If a doc has not been touched in six months, she pings the manager. Not to scold, to ask what changed. Usually something did, and the doc did not catch up.

    What we noticed after a year

    Two patterns showed up that we did not predict.

    First, the docs made lateral moves easier. When an engineer was considering switching teams, they read the target manager’s doc before the coffee chat. The conversations got sharper. Fewer people joined a team and then discovered the manager ran things in a way that did not fit them.

    Second, the docs became a mirror for the managers themselves. Writing “how I handle disagreements” forced people to notice that they did not have a consistent approach. Several managers told us the writing changed their behavior more than any training we had run.

    The manager doc is not a framework. It is one page of honest prose that a team can point at when something feels off.

    That is enough.

  • Kill the quarterly roadmap, keep the direction

    Kill the quarterly roadmap, keep the direction

    Two years ago we kept a proper roadmap. Quarterly planning weeks, OKR drafts in Notion, a review meeting every other Friday, and a Linear project called Q3 Commitments that we updated on Tuesdays and lied about on Fridays. We shipped things. We also spent about six engineering weeks per quarter arguing over rows in a spreadsheet.

    We stopped doing that in March. What replaced it: a single Notion page called Next six months, in rough order. It fits on one screen. It has no dates past the current month, no confidence percentages, and no owner column.

    What the page looks like

    Three sections, always:

    1. Now. Two or three things we are building this week and next. Each links to a Linear ticket.
    2. Soon. Four to eight things we intend to start inside the next quarter. Ordered top to bottom by priority. No dates.
    3. Later, probably. Bets we think matter for the six month horizon but have not committed to. Read the room, not the calendar.

    The page has a Last edited line at the top. If it has been more than three weeks, someone owes the team an update on Slack.

    What we killed with it

    • The quarterly planning offsite. We used to lose a Thursday and half a Friday to it.
    • The OKR grading meeting. Nobody misses it.
    • The roadmap in Figma that lived in parallel to the Linear board and disagreed with it by week three.
    • The reforecast conversation, where we pretended a plan drafted in January still described reality in April.

    We kept the direction. The company still has a one paragraph statement of what we are building over the next 18 months. It sits at the top of the same page. Every commit against Now and Soon should be defensible against that paragraph.

    Why the world changing is fine

    When a competitor ships something surprising, or a big customer hits a wall, or Datadog tells us the ingestion pipeline is cracking, we open the page and reorder it. That takes an hour, not a planning cycle. The team sees the change on Slack the same day. Nobody asks whether we are missing a Q3 objective, because there is no Q3 objective to miss.

    The trade we made: we gave up the theatre of certainty. We got back the six weeks a year we used to spend rehearsing it.

  • Why we killed the daily standup for a 15-minute doc

    Why we killed the daily standup for a 15-minute doc

    Our daily standup used to run 22 minutes on a good day. Ten engineers, one PM, one designer, all half awake, waiting their turn to recite tickets that lived in Linear anyway. We killed it in March. What replaced it is a single Notion page called Morning Doc, and it takes each of us about 90 seconds to fill in.

    How the doc works

    Every engineer, PM, and designer on the delivery pod owns a row. By 10am local time, each owner drops three lines under their name:

    • Yesterday: what shipped or moved, linked to the Linear ticket.
    • Today: the one thing they intend to close before EOD.
    • Blocker: a person, a decision, or a dependency. If none, they write none.

    That is the entire contract. No status colors, no percentages, no vibes. If your row is empty at 10:01, our engineering lead pings you once in Slack. Miss it twice in a week and you owe the pod a coffee run.

    Blockers move to threads, not meetings

    The rule we care about most: blockers do not sit in the doc. The moment someone writes one, they cross-post it into #pod-delivery as a thread with the format Blocker: [who I need] [what I need] [by when]. Whoever owns the answer replies in that thread. Our internal SLA is one hour during working time. Last month we hit it 94 percent of the time, measured with a small GitHub Action that scrapes reply timestamps.

    If a blocker sits unanswered past noon, it gets escalated to the pod lead. That has happened four times this quarter.

    What we gained, and what we gave up

    The wins are boring and real:

    1. We got roughly 110 engineer-minutes back per day across the pod.
    2. Blockers surface in writing, so Thursday retros have receipts instead of memory.
    3. Nobody performs progress for an audience. The doc rewards specificity over storytelling.

    What we gave up is real too. New hires miss the social glue of seeing faces every morning, so we kept a 20-minute Tuesday pod sync for demos and messy conversations. Designers occasionally want a live thinking-out-loud session, and we book those ad hoc in Figma instead of pretending standup was the right container.

    The morning doc is not clever. It is a shared page with a deadline and a Slack rule attached. But it turns out most of what standup gave us was the deadline, and most of what it cost us was the meeting.

  • How we unbreak a Wednesday sprint without cancelling it

    How we unbreak a Wednesday sprint without cancelling it

    Every team we know has had that sprint. Monday standup looked fine. Tuesday morning a payment webhook started dropping in staging, one engineer went out sick, and the design review pushed the checkout redesign back by two days. By Wednesday afternoon the burndown on our Linear board was flat, six tickets deep, and the sprint goal read like fiction.

    We used to cancel sprints in this situation. We stopped doing that around a year ago. Cancelling costs us the retrospective, the sense of finishing something, and the muscle memory of shipping on a cadence. What replaced it is a Wednesday recovery ritual that we run in about forty minutes.

    The Wednesday triage, not another standup

    We block thirty minutes on Wednesday at 2pm called “Sprint check”. It only fires when the burndown deviates more than twenty percent from the ideal line, which our Datadog dashboard flags in a Slack channel called #eng-signals. If the sprint is on track, the meeting is cancelled by 1:45pm and nobody joins.

    When it does fire, three people attend: the engineering lead for the squad, the product manager, and whoever picked up the on-call pager that week. No designers, no wider group. The point is a fast, honest read on the remaining ten working hours across four engineers.

    The question we ask is not “can we still finish everything?” It is “what one thing, if shipped by Friday, would make this sprint worth having run?”

    That one question forces a decision that the daily standup rarely produces. Standups report status. Wednesday triage rewrites the plan.

    Cut scope in the second half

    Once the anchor ticket is named, we walk the remaining Linear tickets and sort them into three buckets. We do this on a shared Notion page titled “Sprint 47 midweek reset” with three headings and drag ticket links under each.

    1. Ship this week. The anchor ticket and anything on its critical path. Usually two or three tickets.
    2. Defer to next sprint. Work that is not blocking anyone. Move it back to the backlog with a comment explaining why.
    3. Drop, do not defer. Tickets that felt urgent on Monday and no longer do. These get closed with a short note. If they matter again, someone will reopen them.

    The third bucket is the one that saves us. Roughly a quarter of what we plan on Monday gets dropped rather than deferred, and none of it has come back to bite us in the four sprints we have tracked this pattern.

    Slice the anchor, do not shrink it

    The highest value ticket is where teams tend to lie to themselves. On Wednesday we do not promise a smaller version of the same scope. We split the ticket into two Linear issues, and the parent becomes an epic.

    Take our checkout redesign example. The original ticket read: “Ship the redesigned checkout flow with saved cards, address autofill, and Apple Pay.” By Wednesday it was clear we had ten hours of engineering work left and about twenty hours of scope. The split looked like this:

    • PAY-412: Ship the redesigned checkout behind a feature flag, five percent rollout, saved cards only. Owner: Priya. Estimate: eight hours.
    • PAY-413: Address autofill and Apple Pay under the same flag. Owner: unassigned. Moved to next sprint.

    The slice we ship on Friday is a real, running thing in production, even if it sits behind a flag at five percent. Next sprint we widen it. What we avoid is the trap of promising the whole checkout by Friday, then delivering nothing and calling it a spike.

    The rolling change log

    Every scope change goes into a single Notion page we call the Sprint Ledger. One page per sprint, appended to as things move. Each entry has a timestamp, the ticket ID, what changed, and one line of why.

    Wed 14:32  PAY-401  Dropped. Duplicated by PAY-397 already in progress.
Wed 14:35  PAY-412  Split from PAY-388. Anchor for the week.
Wed 14:41  ONB-215  Deferred. Blocked on design; no unblock this week.

    The ledger takes about six minutes to fill in during triage. It is read twice: once by the wider squad on Wednesday afternoon, and once by the retro facilitator on the following Monday. Nobody hunts through Slack scrollback trying to remember what changed and why.

    What we get back

    Four things, measured over ten sprints since we started running this ritual:

    • We now finish about eighty percent of our stated sprint goal by Friday, up from around fifty percent when we would grind on the original plan or cancel outright.
    • Retros focus on cause, not blame. The ledger tells us what happened; we can talk about why.
    • Product managers push back less on Wednesday cuts, because the anchor is preserved and the ledger makes the trade visible.
    • On-call load in the second half of the sprint dropped, because we stopped shipping half finished work under time pressure.

    None of this requires new tooling. Linear, Notion, Slack, one recurring calendar block, and a rule about when it fires. The hardest part is not the process; it is the willingness on Wednesday afternoon to say out loud that Monday’s plan is no longer the plan, and to write down what replaced it before the day ends.