Writing That Works

Writing Is the Medium

On a remote team, writing isn't about the work — it is the work interface. Your teammates don't sit next to you. They don't see you thinking hard at your desk. Most of what they know about your work, your progress, and your judgment, they know from your writing: your Slack messages, your PR descriptions, your updates, your docs.

That means writing quality isn't a nice-to-have or a personality trait. A brilliant fix explained in a confusing message lands worse than a decent fix explained clearly. If your writing is hard to parse, your work is hard to see.

Here's the good news: workplace writing is not literature. It's a learnable craft with a handful of mechanical rules that cover 90% of situations. You don't need to be a natural writer. You need to know the rules in this module and apply them until they're habit. Every rule below exists to save your reader time — that's the whole philosophy.

BLUF: Bottom Line Up Front

BLUF is a briefing standard borrowed from the military that has been adopted across the tech industry: state your conclusion or request first, then give context after. Not the other way around.

Most people write chronologically — they narrate their journey and arrive at the point at the end, because that's the order in which they experienced it. That's natural for the writer and terrible for the reader. Watch what burying the lede looks like:

The actual ask is in line 7 of 8. A reader skimming twenty messages will miss it entirely — and merge the PR. Now the BLUF rewrite:

Why this works:

• Readers triage. Everyone scans their messages deciding what needs attention now. The first line is your one guaranteed impression — spend it on the point, not the preamble.
• Many readers only read the first line. With BLUF, those readers still get the essential information. With a buried lede, they get your morning schedule.
• Detail is opt-in. The people who need the full context keep reading. The people who don't are done in three seconds. Everyone gets exactly the depth they need.

A quick self-test before you hit send: read only your first sentence. If someone read nothing else, would they know what you need from them? If not, cut and paste your last sentence to the top — that's usually where the point is hiding.

The No-Hello Rule

Never send "hi", "hey, quick question?", or "got a sec?" as a standalone message and then wait for a reply. Send the whole question in your first message. This rule is so widely shared across the industry that it has a canonical reference site: nohello.net.

The Math of a Naked Hello

Walk through what a bare "hi!" actually costs:

• You send "hi!" at 10:00 your time. Zero information has moved.
• Your teammate is heads-down, or in a meeting, or — because we work across time zones — asleep. They see it at 16:00 your time and reply "hey, what's up?"
• Now you're away. You see their reply the next morning and finally send the actual question.
• A full day has passed and the question has only just been asked. With the question in message one, they could have answered at 16:00 — or better, you might have found the answer was in a doc they could link in seconds.

A naked hello costs a full round-trip before any information moves. Across time zones, a round-trip can be hours or a whole day. The same math applies to "can I ask you something?" (the answer is always yes — just ask it) and to meeting scheduling ping-pong ("can we meet this week?" → "sure, when?" → "when are you free?" — three round-trips and still no meeting).

Note the nuance: this is not a ban on warmth. "Hi Sam! Hope the launch went well —" followed by your actual question in the same message is great. The rule is only that the greeting must never arrive alone.

Anatomy of an Ask

"Can you look at X?" is technically a request, but it outsources all the thinking to the reader. Look at what? How deeply? By when? What happens if they can't? A complete ask answers all of that up front. It contains four parts:

• Context — one line. Why this matters, or where it came from.
• The actual ask — explicit and specific. What exactly do you want them to do?
• The deadline — when you need it by.
• The default action — what you'll do if you don't hear back, so silence never blocks the work.

Compare:

Some people hesitate to include deadlines because they feel pushy. At Hireboard we see it the opposite way: deadlines are kindness, not pressure. A deadline lets your reader triage honestly — "noon tomorrow" tells them they can finish their current task first, or tells them immediately that they can't make it so they can say so now rather than disappoint you later. "When you get a chance" gives them nothing to plan around and quietly converts your request into a lingering guilt object in their inbox.

The same goes for the ask itself. Adapted from Brené Brown's much-quoted line, "clear is kind": explicit is kind, vague is cruel. Vagueness feels polite to the writer but transfers all the work of interpretation to the reader — and sets them up to guess wrong.

The default action deserves special mention because it's the part most people skip. Stating "if I don't hear back, I'll do X" means no response can ever block you. The reader can veto, approve, or say nothing — and in all three cases, the work moves forward. It also removes any sting from the deadline: you're not demanding their time, you're offering them a window to weigh in.

Status Updates People Actually Read

Updates are where overcommunication either shines or dies. A good update can be skimmed in ten seconds and understood without a single follow-up question. The standard format has four parts:

• What changed — what actually happened since last time. Shipped, decided, learned.
• What's next — your plan for the next interval, so people can catch misalignment early.
• Blockers — what's stopping you, or explicitly "none". Never make people guess.
• Need from you — the asks, addressed to specific people. If this section is empty, say so; readers relax and read the rest at leisure.

The craft that makes updates skimmable is bolded leads: start each bullet with the two-to-five bolded words that carry the point, then elaborate after. A reader scanning only the bold text should get the full story arc. That is the ten-second skim; the plain text after each lead is the opt-in detail, exactly like BLUF at the level of a single bullet.

One habit to steal: write the "need from you" section first. It's the part your readers care most about, and writing it first often reveals that the real purpose of your update is a buried ask — which should then lead the message.

Threads and Formatting

Slack mechanics are part of writing. The same words, badly placed or badly formatted, cost the team real attention. House rules:

Thread Discipline

• Reply in thread, not in channel. Threads keep the channel scannable — someone catching up sees ten topics, not two hundred interleaved messages. Use "also send to channel" only when the outcome genuinely needs everyone's eyes, like a decision or a resolution to an incident.
• One topic per message. A message with three unrelated asks gets one answered and two forgotten, because the reply threads can't untangle them. Three topics, three messages, three clean threads.
• Don't fork resolved threads. If a thread reached a conclusion and you have a new question, start a new message and link the old thread.

Formatting for Scanability

• Bullets over paragraphs for anything with more than two items. Walls of text hide structure that bullets reveal.
• Bold the leads, same as in updates — let a skimmer get the gist from bold text alone.
• Code blocks for code, logs, and errors — never screenshots of text. Screenshots can't be searched, copied, or diffed, and they're unreadable on mobile. If it was ever text, share it as text.
• Link the artifact you're discussing. "The PR", "that doc", "the flaky test" — every one of those should be a link. Ten seconds of your linking saves every reader a search.
• Edit typos; don't send corrections. A follow-up message that just says "*tomorrow" is a new notification for every member of the channel. Edit the original instead.

When Threads Graduate to Docs

Slack is where thinking happens; docs are where knowledge lives. Slack is a river — messages flow past and are effectively gone in a week. So the rule is: decisions, and anything you've referenced twice, get written down — in the decision log, a runbook, or the relevant README — and the doc gets linked back into the thread where the discussion happened.

Signs a thread has graduated:

• A decision was made. Two weeks from now, "why did we choose Postgres for this?" should have an answer that isn't "scroll through #eng-backend from March." Log the decision, the alternatives considered, and the reasoning — three sentences is plenty.
• You've explained it twice. The second time you type the same explanation, stop: write it once in a doc, and from then on answer with the link. Every repeated answer after that costs seconds instead of minutes, and the doc improves each time someone asks a question the current version doesn't cover.
• It's operational knowledge. How to run the migration, what to do when the queue backs up, who to page — runbook material. If it lives only in someone's head or a months-old thread, it fails exactly when you need it most.

The closing move matters: after writing the doc, post the link back in the original thread. That's what connects the river to the library — future readers who find the thread via search get routed to the canonical version.

Tone: Warmth, Directness, and Text

Text strips out tone of voice, facial expression, and timing — the channels that normally carry warmth. A message you write in a perfectly friendly mood can read as cold or annoyed on the other end. Two habits fix this, one for writing and one for reading:

Add Warmth Back Deliberately

Since text subtracts warmth, add it back on purpose. Softeners ("when you get a chance — no rush before your launch"), a little acknowledgment before a request ("thanks for turning the last one around so fast"), emoji in moderation, and yes — exclamation points are completely fine in US workplace writing. "Thanks!" reads as warm; a bare "Thanks." can read as icy to American eyes. None of this contradicts BLUF or explicit asks: warmth is seasoning on a clear message, not a replacement for one.

One caution: avoid sarcasm in text. Sarcasm depends entirely on tone of voice, which text doesn't carry. "Oh great, another deploy on Friday" might be an affectionate joke in your head and read as bitter complaint on screen — especially across cultures and language backgrounds. Save it for video calls, where your face can do the work.

Read With Positive Intent

The mirror-image habit: when you receive a terse message, assume positive intent. "Fix the header" from a teammate is almost never anger — it's someone typing fast between meetings, on a phone, or in their fourth language. Read every ambiguous message in the most charitable voice available, because statistically that's the accurate one.

Relatedly: direct requests are normal, standard American workplace style — not rudeness. "Please send me the report by Friday" is polite, complete, professional English. Nobody who writes that to you is upset, and — just as important — your own directness will be read as normal too. You do not need three lines of apology cushioning a one-line request. Clear ask, warm tone, done.

Knowledge Check

Test your grasp of the writing standards before moving on to the practice questions.