Velo Blog

Tag: writing

  • The PRD template we abandoned

    The PRD template we abandoned

    For eighteen months, every feature at Velo started the same way. Someone opened a Notion page called “PRD Template v4,” scrolled past six pages of headings, and started typing. Problem statement. Goals. Non-goals. Success metrics. User stories. Edge cases. Rollout plan. Open questions. Appendix.

    By the time the doc reached our Thursday product review, it was 2,400 words of dutiful prose. When we asked what the user would do differently after we shipped, the room went quiet.

    What the template was hiding

    We reread twelve PRDs from Q1 and Q2. A pattern showed up in the verbs.

    • “Improve onboarding” appeared in four docs.
    • “Optimise the flow” showed up in five.
    • “Reduce friction” was in nine of the twelve.
    • “Increase engagement” closed out most success sections.

    None of these verbs pointed at anything a human could do or fail to do. They were placeholders for thinking, and the template rewarded us for placing them. Six pages of scaffolding meant six pages to fill, and the easiest way to fill six pages was to reach for words that meant almost anything.

    The reviews got worse in a specific way. Engineers would ask a sharp question on page one, and by page five we had lost the thread. Design would flag an interaction we had not considered, and someone would promise to “cover it in the appendix.” The appendix became a graveyard. In one memorable case, a Linear ticket sat in Backlog for eleven weeks because the PRD had three conflicting definitions of “activated user” and nobody wanted to be the person to pick one.

    We had built a document that made disagreement expensive to surface.

    The one-page brief

    In August we tried something smaller. Three prompts, one page, hard cap at 400 words.

    1. Problem. What is going wrong for a specific person on a specific day? Name the person by role, not persona.
    2. Target user. Who feels this problem most acutely, and which of them do we have access to for interviews within the next week?
    3. First observable behaviour. What will this person do after we ship that they cannot do or would not do today? Describe the action, not the outcome.

    That third prompt did most of the work. “Increase engagement” fails it. “The ops lead exports the reconciliation report as a CSV before their Monday standup” passes it. You can watch a person do that or not do it. You can ask them why they did not. You can count it in Datadog.

    We wrote the first brief for a billing export feature. It took forty minutes. The Thursday review took nineteen. Two engineers pushed back on the target user selection, we agreed to run three interviews before writing a line of code, and the ticket moved to In Progress the following Tuesday.

    What we gained

    The obvious thing was time. Our median PRD used to take a product manager somewhere between four and seven hours to draft, plus another two in edits after review. The brief takes forty to ninety minutes. Reviews compressed from an hour to under thirty because there was nowhere to hide vague thinking.

    The less obvious thing was that engineers started reading the doc. When something is six pages of prose, the second engineer on a project skims. When it is one page and the third bullet is a specific behaviour, they read it, and they argue. We stopped confusing “we have a PRD” with “we know what we are building.” Writing a brief did not feel like progress in the way writing a six-page PRD had felt like progress. That turned out to be honest.

    What we lost

    We lost some things we miss. The old PRD forced us to enumerate edge cases up front, and the brief does not. Two of our first four briefs shipped with a rollback plan improvised in a Slack thread the morning of launch. We have since added a lightweight “what breaks” checklist that lives next to the brief but is not part of it, and reviews now include a five-minute walkthrough of that checklist.

    We also lost some institutional memory. A six-page PRD, for all its flaws, was a decent artefact for the person joining the team six months later. Our briefs are terse enough that a new engineer opening one in GitHub cannot always reconstruct why we made the calls we did. We are experimenting with a short decisions log per feature, kept in the same Notion database, updated as we go. It is not a Figma spec and it is not a design review transcript, but it stops the “why did we do it this way” question from getting answered with a shrug.

    What we would tell you

    If your PRD template has more than three prompts, ask the last five people who filled one in whether the extra prompts changed a single decision. If the answer is no, cut them. The template is not neutral. It teaches your team what counts as thinking.

    The verbs are the tell. If your docs are full of them and nobody has flinched in a review this quarter, the template is doing the flinching for you.

  • What happened when we replaced standup with a doc

    What happened when we replaced standup with a doc

    The reason we cancelled the 9:15

    Our morning standup ran for eleven months before we killed it. Fifteen minutes on paper, twenty-two in practice, five people on video, one person still chewing toast. We tracked the cost for a quiet month: eleven engineers, four days a week, roughly nine hours of collective time each week vaporized into “yesterday I worked on the invoice bug, today I will keep working on the invoice bug.”

    The trigger was Linear. We had migrated our ticket board over from Jira, and the state of every ticket was suddenly legible without a human reading it aloud. Whatever the standup had been for, it was no longer for status.

    We wrote a shared Notion page called Daily. Each morning, before 10:00, you posted three lines: what shipped, what you are on, what is blocking you. That was the whole ritual. No meeting.

    Week one and two: something went wrong

    The first Monday felt like a small miracle. Everyone got the extra half hour, the doc filled up by 09:47, and we all stayed at our desks. By Thursday, two things were off.

    The doc was thinner than we expected. People wrote “same as yesterday” or copied their previous line and edited the date. The prose that had felt lively when spoken went dead when typed. Morale dipped too, in a way we did not predict. Not a crash, more like the room got quieter. Our head of design put it best in the retro:

    I did not realize how much of my sense of the team came from watching Priya groan about her PR review queue and Marcus talk about his kid’s soccer game. The doc has none of that. It reads like a receipt.

    Slack traffic went up during those two weeks, in a way that surprised us. Random channels filled with the small talk that had been living, uninvited, inside standup. We had removed the container without moving the contents anywhere. The contents leaked.

    The other loss was harder to measure. In standup, someone would say a sentence and someone else would say “wait, back up,” and a small course correction would happen in ninety seconds. In the doc, that same correction became a threaded Slack conversation that took two hours and ended with “let’s hop on a quick call.” We had traded one meeting for many smaller ones.

    Week three onward: the writing got serious

    Around the third week, the doc improved. A few things changed at once:

    • The team stopped treating the entry as a chore and started treating it as a note to a colleague. Entries got longer, more specific, funnier.
    • Blockers became first class. If you wrote “blocked on the Stripe webhook signature bug,” someone unrelated would read it over coffee and drop a link to the fix.
    • Async engineers in Lisbon and Toronto stopped feeling like second tier attendees. Their entries carried the same weight as the ones written in the London office.

    The deeper win was the writing itself. Engineers who had been quiet in meetings wrote sharp, thoughtful updates. One of them told us she had spent every standup rehearsing her sentence and missing what other people said. The doc gave her back that attention. Our design docs improved in the same period. We are not sure the two are causally linked, but it felt like a muscle getting more reps.

    The Wednesday sync, and why it stayed

    We tried holding out on the meeting free plan for a full month. It did not last. By week five we had put one meeting back on the calendar: a thirty minute sync on Wednesday at 10:00, camera on, no agenda beyond “how is the week going.” We call it Wednesday. That is the whole name.

    Wednesday is not a status meeting. If you tried to give a status update in it, someone would gently redirect you to the doc. It is where the soccer game goes, where the “I hate this ticket” goes, where the “I think we should reconsider the pricing page rewrite” goes. It has run for fourteen months now and we have cancelled it twice, both times for a company offsite.

    The compromise on paper:

    1. Monday through Friday: the Daily doc, posted by 10:00.
    2. Wednesday at 10:00: the thirty minute human sync.
    3. Friday afternoon: a short written retro in the same Notion space, three prompts, no meeting.

    Time saved per engineer, measured against the old standup, is roughly six hours a month. That number is real. What is less measurable, and what we think matters more, is that our written record of what happened each week is now searchable. When a new hire joins, we point them at three months of Daily entries and they get context that used to live only in people’s heads.

    What we would tell a team about to try this

    Two things. First, the social contract of standup is doing work you cannot see. If you remove the meeting without replacing the social part, the team will feel it within a week and blame the doc. Put the social part somewhere on purpose. Second, the doc will be bad for two weeks. Do not judge it before then. The writing muscle needs reps, and the first entries will read like receipts because the team is still thinking in bullet points from the meeting they no longer have.

    This setup would not work for a sales team, or a team spread across more than three time zones, or a team that responds to Datadog pages every hour. It works for eleven engineers and four designers who write for a living anyway. Your mileage will vary. Ours has not, in a year and change.