The same request, rewritten: the writing that actually moves projects
In a distributed team, writing is where the work happens. Before-and-after examples of the five things a project manager writes every day: requests, issue descriptions, decisions, status updates and escalations.
Most project managers never get taught to write. They get taught templates. But in a remote or hybrid company, requests, decisions, plans, status and escalations all travel as text, and a PM who writes clearly saves dozens of hours a week across the team. One who writes vaguely creates meetings, rework and mistrust.
Here are the five forms that matter most, each with a real before-and-after from the four projects in Projects, For Real.
The one test
GitLab's TeamOps guidance names the core skill: low-context communication. Assume the reader knows nothing about the topic. Give them the background, the specific request, links to the source of truth, definitions of unusual terms, the deadline and the reason. Before you send anything, ask: could a capable colleague who joined the company yesterday act on this without asking a question? If not, add what they'd need. In an async team, every follow-up question can cost a day.
1. The request
Every request needs five things: who (an @-mention, not a CC), what (the action, in one sentence), why (so they can prioritize or find a better way), by when (a date, and what happens if it's missed) and where (a link to the issue, document or line in question).
@chen.wu, could you confirm the cost-center field mapping in the table under Mapping v2 in this issue's description? Specifically: Workday Cost_Center_Reference_ID → Spendwise department_code.
Why: Apex starts configuring approval routing on Mon 19 Jul, and routing keys off department code. If the mapping is wrong we'll rebuild routing (~3 days).
By: end of Fri 16 Jul. If you can't get to it, tell me by Wed and I'll ask Ravi to check against a Workday report instead.
The rewrite is longer. It costs Chen thirty seconds to understand and costs the project zero follow-up messages. And because it lives on the issue, anyone checking the mapping later sees the question and the answer.
Answering is the other half. “Will do” doesn't tell the requester whether to wait or find another route. Reply with a date or “done”: “I can do this Thursday. If that's too late, Ravi has the same report access.”
2. The issue description
An issue is the unit of work, and its description is that work's single source of truth. The structure is deliberately boring: problem, proposal, out of scope, acceptance criteria, links.
Problem. Forecasts need at least 8 weeks of throughput history to be meaningful. Milestones that existed before the feature flag was enabled have no history, so on launch every existing team would see “Not enough data” for two months.
Proposal. A background migration that computes weekly closed-issue counts per milestone and per epic for the trailing 12 weeks, from existing closed_at timestamps. Batched, throttled per the database guidelines.
Out of scope. Weight-based history (follow-up #44140). Iteration cadences (deferred).
Acceptance criteria. For a milestone created ≥ 12 weeks ago, the history table has 12 weekly rows. Runs on GitLab.com in < 6 h with no severity 3+ alerts. Re-running is idempotent.
Rollback. Disable via flag; rows are inert without the main flag.
“Out of scope” heads off scope creep during review. Acceptance criteria define done. Links tie the work to the decision that justified it.
3. The decision
When a decision needs input or buy-in, write it up. GitLab's SPADE structure works at any size: Setting, People, Alternatives, Decision, Explain.
Setting. We need a go-live date to baseline the schedule. Constraints: (1) Finance blackout covers the last 3 and first 8 business days of each quarter (Q3 FY28 closes 31 Oct); (2) the legacy tool's support ends 31 Dec; (3) employees submit most expenses in the first week of the month; (4) a two-week UAT is needed after SIT. Earliest realistic date: late September. Reversible until we announce the date to employees on 2 Aug.
People. DRI: Daniel Okafor (Sponsor). Consulted: the Controller, AP, Field Ops, Payroll, integrations, the vendor and the implementation partner.
Alternatives. A. Mon 27 Sep: earliest, most benefit, but collides with September's month-end AP close and submission peak. B. Mon 4 Oct: after month-end, ~13 business days before the Q3 blackout, hypercare finishes before Q4 close; two days less float. C. Mon 8 Nov: most float, but inside Q4's blackout; next window late November near holidays; ~$45k of benefit lost per month of delay.
Decision. Option B: go-live Monday 4 October 2027. Fallback: 18 October, decided at go/no-go on 29 Sep.
Explain. B is the only option that avoids both month-end AP close and the quarter-close blackout while leaving a fallback inside the same window. A's one-week benefit gain doesn't justify the close risk.
The part people skip is the part that matters most later: the options that lost, and why. Six months on, when someone asks “why didn't we go live in September?”, the answer takes thirty seconds to find.
4. The status update
A good status answers four questions in this order: what's the overall state, in one line, with a reason; what changed; what's next; and what do you need from the reader. Most executives read the first two lines. Make them carry the message.
Status: Needs attention. Pilot wave (M2) is on plan for 14 Sep acceptance, but firewall approvals for the runner network are 6 days late and now on the critical path.
Done (iteration 3): 312 of 500 pilot repositories migrated with full history (62%). 9 of the top-40 CI templates built and passing. Pilot team A onboarded (41 developers).
Changed: New risk R-09: firewall change pending in Meridian's change board since 31 Aug. If not approved at the 7 Sep CAB, pilot acceptance moves to 21 Sep (no cost impact).
Next: remaining 188 pilot repos; 6 more templates; pilot team B.
Needs: @thomas.whitfield, could you ask Martin Cole to put the runner firewall change first on Tuesday's CAB agenda? Details: RAID item #87.
Hours: 642 of 1,980 used (32%) against 40% of schedule elapsed.
5. The escalation
An escalation is a request for help from someone with more authority when you're blocked and have done what you can. Good ones are short, factual and offer options:
Escalation: Spendwise SSO/SCIM connector, needs your help by Friday
@daniel.okafor: the vendor's Okta connector has failed our SSO tests for 9 business days (issue I-04). Their PM has twice moved the fix date without a root cause. If it isn't fixed by 31 Aug, SIT slips ≥ 1 week and the 4 Oct go-live is at risk.
What I've done: daily follow-up with their PM; cited the SLA (§7.2); tested a workaround (local accounts for non-SSO tests).
Ask: an exec-to-exec call with Spendwise's VP of Customer Success this week to get a committed date and a named engineer. Talking points are drafted in I-04.
Options if no fix by 31 Aug: (a) go live with SAML-only SSO and manual provisioning for 4 weeks (+0.5 FTE in IT Ops); (b) move go-live to the 18 Oct fallback.
Executives welcome escalations like this. The facts are in place, the work done so far is visible, and the decision is framed.
Chat coordinates; documents record
Use public channels, not DMs, so others learn from the answer. Use threads. Link to the source of truth instead of pasting content that will go stale. And move decisions out of chat: if a decision happens in Slack, write it into the issue and link back.
One last rule from GitLab's guidance on generated text: if you use AI to help write, you own every word. Read it, verify the facts and numbers, and don't hide behind a disclaimer.
How students practice this
Week 2 is entirely about the workbench and these five forms. After that, every weekly deliverable includes at least one request, one status and one decision written to this standard, and every Friday review starts with someone's writing on the screen.
Adapted from Projects, For Real, chapter 8. The projects, people, vendors and numbers are the book's fictional case studies, set against GitLab's publicly documented practices. Gantt Guild is not affiliated with GitLab Inc.
