Scrolls
5 min read
On this page

Writing Clear Messages

A vague Slack message wastes two people's time: yours to write and theirs to decipher. When someone reads your message and has to ask a follow-up question before they can help, you have doubled the communication cost. When they guess wrong about what you meant and spend 30 minutes on the wrong thing, you have wasted more than a meeting would have cost.

Clear messages are not about being formal or verbose. They are about being specific. Say what you need, provide the context, and state the deadline. The reader should be able to act on your message without asking a single follow-up question.

The Structure: Context, Ask, Deadline

Every message that requests something from another person should contain three elements. You do not need labels or headers -- just make sure the information is there.

Context:   What you are working on and why you need help
Ask:       The specific thing you need from the reader
Deadline:  When you need it by

Example:
"I'm updating the billing service to support annual plans (JIRA-1234).
The subscription model needs a new 'billing_period' field, and I'm not sure
whether to add it to the existing subscriptions table or create a new
billing_configs table. Can you weigh in on the schema approach?
I'd like to start implementation tomorrow afternoon."

Compare that to the message it replaces: "Hey, got a minute to chat about the billing service?" The first message can be answered asynchronously in 2 minutes. The second requires scheduling a synchronous conversation.

Anti-Patterns in Messaging

The Naked Greeting

Bad:
"Hey"
[waits for response]
"Quick question"
[waits for response]
"About the API"
[waits for response]
"Can you check if the rate limiter is working?"

Good:
"Hey, can you check if the rate limiter on /api/v2/search is working?
I'm seeing 200 responses even after 100 requests/second from the
load test. Dashboard: [link]. Config: [link]."

The naked greeting turns what should be a 30-second async exchange into a 10-minute synchronous drip. Send the whole message at once. Always.

The Screenshot Without Context

Bad:
[screenshot of an error]
"Is this expected?"

Good:
"Getting this error when running the import job on staging:
[screenshot]
This started after yesterday's deploy of PR #312. The job runs
fine locally. I've checked the env vars and they match staging.
Any idea what's different about the staging environment?"

A screenshot is not a message. It is an attachment. The message explains what you were doing, when it started, what you have already tried, and what you think might be wrong.

The Multi-Topic Message

Bad:
"A few things: (1) can you review my PR? (2) the staging deploy is
broken, (3) are we still doing the team lunch on Friday? (4) I think
we should refactor the auth module."

Good:
- Send the PR review request in the PR itself or the code-review channel
- Report the staging issue in the incidents or ops channel
- Ask about lunch in the social channel
- Start the refactoring discussion in a design-discussions channel or RFC

When you bundle unrelated topics, some will be addressed and others will be lost. Different topics belong in different contexts with different audiences and urgencies.

Writing for the Scanner

People do not read messages. They scan them. If your key point is buried in paragraph three, it will be missed. Structure your messages so the important information is visible at a glance.

Techniques:

- Lead with the ask. Don't bury it after three paragraphs of background.
- Use line breaks. A wall of text is harder to scan than short paragraphs.
- Bold the key question or action item if your tool supports it.
- Use bullet points for lists of items, not inline comma-separated lists.
- Put links on their own line, not inline where they break the flow.

Compare:

Hard to scan:
"So I was working on the migration and I noticed that the users table
has a column called 'status' that's an integer but the application code
treats it as a string enum and I think this might be causing the bug
where users show up as 'null' status on the admin dashboard, can someone
confirm whether we should cast it in the query or fix the column type?"

Easy to scan:
"Bug: users show as 'null' status on the admin dashboard.

Root cause (I think): the 'status' column in the users table is an
integer, but the application code expects a string enum.

Question: should we fix the column type, or cast in the query?

Affected: admin dashboard user list, possibly the API user endpoint too.
Dashboard link: [link]"

Same information. The second version can be understood in 10 seconds. The first requires careful reading.

Choosing the Right Channel

Where you post is as important as what you write. A message in the wrong channel either gets no response or annoys people who do not need to see it.

Direct message:        Sensitive/personal topics only
Team channel:          Team-specific work discussions
Project channel:       Cross-team project coordination
Help/support channel:  Questions for a broad audience
Incidents channel:     Production issues
Announcements:         Important one-way communication

Rule: if more than one person might benefit from seeing the
question or its answer, do not use a DM. Post it in a channel
where others can find it later.

DMs are the enemy of organizational knowledge. When you DM someone a question and they answer in the DM, that knowledge is trapped between two people. When you post in a channel and get an answer, everyone in the channel benefits, and future searchers can find it.

Requests vs. Notifications vs. FYIs

Not all messages require action, but the reader should not have to guess which type yours is. Make the category explicit.

Request (action needed):
"[Request] Can you approve the terraform plan for the staging
migration? PR: [link]. I need approval by EOD to deploy tomorrow."

Notification (no action, but important):
"[FYI] Deploying the payment service update in 30 minutes.
Expected 2 minutes of downtime on the /checkout endpoint.
No action needed unless you're actively testing checkout."

Information (reference only):
"[FYI] Published the Q3 API usage report: [link].
Key takeaway: search endpoint traffic up 40%, may need to
revisit rate limits next quarter."

The bracketed prefix is optional but helpful. What matters is that the reader knows within the first sentence whether they need to do something, pay attention, or just file it away.

Replying Well

Clear communication is a two-way skill. How you reply is as important as how you ask.

Bad reply:
"Yeah that should be fine."

Good reply:
"Yes, adding the column as nullable is the right approach. Run the
migration before deploying since the new code handles null gracefully.
One thing to watch: the analytics pipeline reads this table directly,
so ping the data team to update their schema. They're in #data-eng."

The good reply answers the question, provides context for the decision, and surfaces a dependency the asker might not have known about. It moves the work forward instead of just unblocking a single question.

When you do not know the answer, redirect rather than leaving the question hanging:

"I'm not sure about the billing schema -- that's more in Sarah's area.
Try asking in #billing-team, she's usually responsive there."

Thread Discipline

In Slack and similar tools, threads keep conversations contained. Use them.

Thread rules:

- Reply in the thread, not in the channel.
- If the thread conclusion affects everyone, post a summary to the
  channel: "Resolved in thread: we're going with option B, shipping
  Thursday."
- Long threads (10+ messages) probably should have been a document.
  Move the discussion to a Google Doc or RFC and link it.
- Do not start a new top-level message to continue a thread
  conversation. It fragments the discussion and loses context.

Editing After Sending

Slack lets you edit messages. Use this when you realize your message was unclear, but be careful about editing in ways that change meaning after someone has already responded.

Good edits:
- Fixing typos
- Adding a missing link
- Clarifying an ambiguous sentence

Bad edits:
- Changing your question after someone already answered the original
- Removing content that makes a response look out of context
- Silently adding important details (add them as a reply instead)

Common Pitfalls

  • The "quick question" that is not quick. If you need 15 minutes of someone's time, say so. Do not pretend it is quick to lower their resistance.
  • Assuming everyone has your context. You have been thinking about this problem for 3 days. The reader is seeing it for the first time. Provide enough background for someone who has not been inside your head.
  • Asking in DMs when a channel would serve everyone. Your question is probably not unique. Post it where future people with the same question can find the answer.
  • No deadline or urgency signal. "When you get a chance" could mean today or next month. Be specific: "by EOD Wednesday" or "not urgent, anytime this week is fine."
  • Pinging without purpose. Tagging someone with @ in a message they were already going to see adds stress without adding information. Tag people when they would not otherwise see the message, or when you specifically need their input.
  • Sending fragments. Each Slack message generates a notification. Sending your thoughts one line at a time generates 5 notifications for a single thought. Compose the whole message, then send.

Key Takeaways

  • Every request message needs three things: context (what you are working on), ask (what you specifically need), and deadline (when you need it by).
  • Send the whole message at once. Do not send a greeting and wait for a response before stating your question.
  • Lead with the ask. People scan, they do not read. Put the important part first.
  • Post in channels, not DMs. Channel conversations create searchable, shared knowledge. DMs create silos.
  • Make the message type clear: is this a request for action, a notification, or an FYI? Do not make the reader guess.
  • Reply with enough context to move the work forward, not just "yes" or "looks good."