Read the first pages of Writing at Work for IT Teams B1–B2

Before you start

Welcome

Welcome! This book is for everyone who works in an IT team and writes in English every day: developers, testers, DevOps and support engineers, product managers and team leads.

Most of the English you use at work is written. Tickets, bug reports, commit messages, code review comments, chat messages, status updates, incident notes. Your colleagues are often in other countries and other time zones, so they read your words hours after you write them, and they can’t just turn to you and ask what you meant. A clear message saves a day. An unclear one can cost a week.

This book shows you how experienced colleagues write these texts: short, clear, polite and easy to act on. Every chapter takes one real kind of text, shows you a good example, explains how it works, gives you the phrases you need and lets you practise. At the end of each chapter, you write your own text and compare it with a model answer.

You don’t need perfect English to write well at work. You need to know what your reader needs, and a few good phrases to say it. That is what this book gives you.

How this book works

There are 24 chapters in four Parts:

Part	Chapters	What you write
1 · Tickets and Bug Reports	1–6	Clear messages, tickets, bug reports, questions, status comments, estimates
2 · Code and Code Reviews	7–12	Commit messages, pull requests, review comments, technical explanations, README files
3 · Team Chat, Email and Planning	13–18	Async stand-ups, chat messages, emails to non-technical colleagues, pushing back, meeting notes, customer replies
4 · Incidents, Documents and Your Career	19–24	Incident updates, postmortems, handover notes, design proposals, feedback, job applications

Do the chapters in order if you can. The early chapters teach habits that every later chapter uses. But if you need to write a bug report tomorrow, go straight to Chapter 3: each chapter also works on its own.

After every six chapters, a Part review mixes everything from that Part. Try it without looking back.

Use the key. All the answers are at the back of the book. When more than one answer is possible, a slash (/) shows them. For rewriting and writing tasks, the key gives a possible answer or a model answer: one good version, not the only one. If your version is clear, polite and has all the information, it is a good answer too.

Use your own work. Every writing task is set in the world of one software team, but you can always write about your own project instead. That is the best practice of all.

How each chapter works

Every chapter has six steps and ten exercises.

Step	What you do
1 · See it in action	Read a real example of the text type and notice what makes it work.
2 · How it works	See the parts of the text, in order, and the key rules.
3 · Useful phrases	Learn ready-to-use phrases, marked B1 or B2.
4 · Practise	Choose, order, complete and rewrite. Exercises 1–7.
5 · Say this, not that	Fix the mistakes that make work texts unclear or impolite. Exercise 8.
6 · Your turn and quick check	Write your own text with a checklist, then do ten quick questions. Exercises 9 and 10.

The B1 phrases are simple and safe: you can use them everywhere. The B2 phrases are a little more precise or more diplomatic. Start with B1, then add the B2 phrases you like.

The levels in this book are a guide to help you choose. They are not official CEFR results.

Meet the Rota team

All the examples in this book come from one team at Northbeam Software, a fully remote company with about 120 people. Its main product is Shiftly, a staff-scheduling app for restaurants, clinics and shops. With Shiftly, managers plan shifts, employees swap shifts with each other, and everyone can see their hours. Shiftly has a web app and a mobile app.

The Rota team builds the scheduling part of Shiftly. They work across five time zones, so most of their communication is written.

Name	Role	Based in
Priya Raman	Backend developer. Careful and thorough, but sometimes writes too much.	Bengaluru
Mateus Costa	Frontend developer. Fast and friendly, but sometimes too short.	São Paulo
Oksana Kovalenko	QA engineer. Very precise, and her bug reports are famous in the team.	Kraków
Kwame Mensah	DevOps engineer. Calm when things go wrong.	Accra
Daniel Reyes	Support lead. He brings the customers’ problems to the team.	Manila
Lena Hoffmann	Product manager. She writes the tickets and talks to the customers’ managers.	Berlin
Sam Okafor	Engineering manager and team lead.	London

Northbeam’s customers in this book are Greenleaf Clinics, the Casa Lumo restaurants and Brightway Pharmacies. Tickets for the product start with SHIFT-, and tickets for the infrastructure start with OPS-.

All the people, companies and products in this book are fictional, and so are the email addresses, which use example.com. The tools are not real brands either: the team uses “the ticket tracker”, “the team chat” and “the code repository”. Your tools may have other names, but the writing works the same way.

Quick guide: writing for a busy reader

Five ideas you’ll meet again and again in this book:

1. Start with the point. Say what you need or what happened in the first line. Details come after.
2. One message, one topic. Two topics? Write two messages, or use numbered points.
3. Be specific. Not “It doesn’t work” but “The Save button shows an error after I change the start time.”
4. Make the next step clear. Who needs to do what, and by when?
5. Be kind and neutral. Write about the problem, not the person. A short “Thanks!” costs nothing.

Ready? Let’s start with Chapter 1.

Part 1 · Tickets and Bug Reports

Chapter 1 · Writing for a Busy, Distributed Team

Goes with Every message you send to your team · Your goal: You can write a short work message that a busy colleague in another time zone can understand and act on in one read.

Your team is spread across the world. When you finish work, a colleague is just waking up. You can’t lean over and ask, “What do you mean?” If your message is unclear, they write back with a question, you answer the next day, and a simple task takes two days. This chapter shows you the habits that clear writers use: put the point first, keep one topic per message and say exactly what you need and by when. They are small habits, but they save your team hours every week.

1.1 See it in action

Mateus Costa (São Paulo) is building the new shift-swap screen in Shiftly. He needs a change to an API endpoint from Priya Raman (Bengaluru). Bengaluru is eight and a half hours ahead, so when Priya starts work, Mateus is asleep. Read his first message, then his second try. (All times are in UTC.)

#rota-team

Mateus Costa 20:50
hi Priya!! how are things? so today I was working on the swap screen and I noticed something strange with the API, when I get the list of swaps sometimes there is no info if the manager approved it or not, so I don’t know what to show to the user, I tried some things but no luck. also design changed the button colours again haha. can we talk about it when you have time?

Priya Raman 03:40
Hi Mateus! Sure. What exactly do you need from the API?

Mateus Costa 12:05
Sorry, just saw this! I need the swap status…

#rota-team

Mateus Costa 20:50
Priya, a request for the swap screen (SHIFT-231): could you add a status field to the /swaps endpoint by Thursday?

Right now the response doesn’t say whether a manager has approved a swap, so the app can’t show “Pending” or “Approved”.

What I need:
– status with one of three values: pending, approved, rejected
– the same field in the list response and the single-swap response

There’s an example response in the ticket. If Thursday is difficult, just tell me and I’ll hide the label for this release. No call needed.

Priya Raman 03:55
Yes, Thursday is fine. I’ll add it to both responses and update SHIFT-231 when it’s on staging.

Notice. In the second version, what does Priya know after reading only the first line? What did Mateus leave out, and why doesn’t it matter? Look at the times: how much time does the second message save?

1.2 How it works

Part	What to write	Example
First line or subject line	The topic and, if possible, what you need	Swap screen: status field needed by Thursday
The point	Your request, question, decision or news, in one sentence	Could you add a status field to the /swaps endpoint by Thursday?
Context	Only the background the reader needs: one to three sentences	Right now the response doesn’t say whether a manager has approved a swap.
Details	Facts, a short list, a ticket number or a link	pending, approved, rejected
Next step	What happens next, the deadline and a plan B	If Thursday is difficult, tell me and I’ll hide the label.

Lead with the point. Experienced colleagues call this BLUF: bottom line up front. Your reader may only read the first line on a phone between meetings, so put the most important sentence there. The story of how you found the problem can come later, or not at all.

One message, one topic. If you have three topics, send three messages (or start three threads). Then each one can get its own answer, and nothing gets lost.

Short paragraphs, plain words. Write paragraphs of one to three sentences. Use short, common words: use, not utilise; help, not facilitate. Name things exactly: the timesheet export, not the thing.

Say what you need and by when. Soon and ASAP mean different things to different people. Give a day and a time, and say which time zone.

Make it easy to act on. Ask questions that can be answered with yes, no or a choice. Offer a plan B, so your colleague can answer without waiting for you.

Tip · Whose Thursday? A deadline like by end of day is unclear when your team is spread across five time zones. Write by Thursday 12:00 UTC or by the end of your Thursday. Many teams use UTC in tickets and chat for exactly this reason.

1.3 Useful phrases

Use	Level	Phrase	Example
Leading with the point	B1	Quick question: …	Quick question: is the swap endpoint on staging yet?
Leading with the point	B1	Could you …, please?	Could you review my pull request today, please?
Leading with the point	B2	The short version is: …	The short version is: the release moves to Monday.
Leading with the point	B1	Just FYI: … No action needed.	Just FYI: staging will be down 14:00–15:00 UTC. No action needed.
Saying what you need and by when	B1	I need … by …	I need the final button text by Wednesday 12:00 UTC.
Saying what you need and by when	B2	Ideally by …, but … is fine too.	Ideally by Tuesday, but Wednesday morning is fine too.
Saying what you need and by when	B2	This is blocking …	This is blocking the swap screen, so it’s my top priority.
Giving context briefly	B1	For context, …	For context, Greenleaf Clinics asked for this last week.
Giving context briefly	B2	(Full) background is in …	Full background is in SHIFT-231.
Making it easy to act on	B1	Option A or B?	Option A (hide the label) or B (wait for the API)?
Making it easy to act on	B1	A quick yes or no is fine.	Can you do it by Thursday? A quick yes or no is fine.
Making it easy to act on	B2	If I don’t hear back by …, I’ll …	If I don’t hear back by Friday, I’ll go with option A.
Making it easy to act on	B2	Happy to jump on a quick call if that’s easier.	Happy to jump on a quick call if that’s easier, but chat should be enough.
Making it easy to act on	B1	Let me know if anything is unclear.	The example is in the ticket. Let me know if anything is unclear.

1.4 Practise

Exercise 1 · Choose the better version. Choose the first line or subject line (a or b) that a busy colleague will understand faster.

1. 1. Question
      
   2. Rota export: are break times missing from the CSV?
2. 1. Hi Kwame, hope your week is going well! I wanted to ask you something about staging, if you have a minute at some point.
      
   2. Kwame, could you restart the staging server today? Tests are failing with a timeout.
3. 1. Greenleaf Clinics: rota PDF fix needed before 20 November
      
   2. Urgent!!!
4. 1. Please check the thing we talked about.
      
   2. Please check the timesheet total in SHIFT-242 (row 3 looks wrong).
5. 1. Can you send it soon?
      
   2. Can you send it by Wednesday 10:00 UTC?