Professional communication
Lab setup
First, make sure you have completed the initial setup.
If you are part of a course
-
Open Terminal. Run the update command to make sure you have the latest code.
$ mwc update -
Move to this lab's directory.
$ cd ~/Desktop/making_with_code/pilot/labs/lab_professional_comms
If you are working on your own
-
Move to your MWC directory.
$ cd ~/Desktop/making_with_code -
Get a copy of this lab's materials.
git clone https://git.makingwithcode.org/founders-studio/lab_professional_comms.git
Software is built by people talking to each other: in pull requests, issues, status updates, messages to clients, and requests for help. Good communication helps people act: a reviewer knows what to check, a client knows what to decide, a mentor knows how to help. In this lab, you'll practice the kinds of writing that software work runs on, and learn to use AI to help you write without producing bullshit.
By the end of this lab, you will be able to:
- Write clear pull request descriptions, issues, and code reviews.
- Write status updates that help a client or mentor act.
- Recognize when to ask for help, and ask for it well.
- Use AI to draft and revise messages while staying responsible for every word.
Writing in the tools
Pull requests
A pull request description tells a reviewer what they need to know to review your change. A good one answers:
- What changed?
- Why? (Link the issue.)
- How was it tested?
- What should the reviewer look at closely?
๐ Open examples/pull_requests.md, which contains three PR descriptions.
With your group, rank them from most to least useful, and explain your ranking.
๐ป Rewrite the weakest description so it answers all four questions.
Issues and bug reports
A good bug report lets someone else see the problem for themselves. It says what you did, what you expected, and what happened instead, with the exact error message and the steps to reproduce it.
๐ป The buggy/ folder contains a small program with a bug. Find it, and
write a bug report in bug_report.md that a teammate could use to reproduce the problem
without asking you anything.
Code review
Review comments should be specific, explain why, and be kind. Compare:
- "This is wrong."
- "This will crash if
postsis empty, becauseposts[0]doesn't exist. Could we check for that first?"
๐ป Review a teammate's PR from the Team workflow lab (or one your mentor assigns). Leave at least three comments: one question, one suggestion, and one thing done well.
Status updates
Clients and mentors don't see your work every day. A short, regular status update keeps them informed, and gives them a chance to help before small problems become big ones. A good update covers:
- Done: what you finished since the last update.
- Next: what you're working on now.
- Blocked: anything stopping you, and what you need to get unblocked.
- Decisions: anything you need the reader to decide, asked as a clear question.
Keep it short. A busy reader should be able to understand it in thirty seconds.
๐ป Write a status update for your partner project (or this week's studio
work) in status_update.md, using the four sections above.
๐ป Trade updates with another team. Could they act on yours? What questions did they still have?
Asking for help
Everyone gets stuck. Being stuck isn't a problem; staying stuck is. Professionals learn when to keep trying on their own, and when to ask.
๐ป As a team, discuss and agree on a rule of thumb. For example: "If I've
made no progress for 30 minutes, I ask for help." Write it in NORMS.md.
A good help request makes it easy for someone to help you. It includes:
- What you're trying to do.
- What you tried, and what happened (exact error messages, not "it doesn't work").
- The smallest example that shows the problem.
- If you asked an AI first, what it suggested, and what happened when you tried it.
๐ป The next time you get stuck on a real problem this week, write a help
request in help_request.md before asking. (If you solved it while writing, note that too.)
Using AI without bullshitting
The philosopher Harry Frankfurt defined bullshit as speech produced without regard for whether it's true. A liar knows the truth and hides it; a bullshitter doesn't care. Language models produce fluent text whether or not it is true, so AI makes it very easy to send bullshit: messages that sound right, but that you haven't checked, don't fully understand, or don't actually mean.
๐ Open examples/ai_drafts.md, which contains several messages drafted by
an AI. With your group, mark:
- Padding: words that add length but no meaning.
- Unchecked claims: statements of fact the sender may not have verified.
- Generic praise or enthusiasm the sender may not feel.
- Promises the sender may not be able to keep.
๐ป Rewrite one of the drafts into something you'd be willing to send.
AI is genuinely useful for communication: drafting when you're stuck, tightening a long message, checking tone, or translating technical details for a non-technical reader. Before you send anything AI helped write:
- Check every factual claim. Is it true? Do you know it's true?
- Cut what you don't mean.
- Make sure you could explain every sentence if someone asked.
- Say how AI contributed, when that matters to your reader.
๐ป Use AI to help draft a message to your client (or mentor) asking for
something you actually need. Apply the four checks, and save both the AI draft and your final
version in client_message.md.
Meetings
Client check-ins and team stand-ups go better with a little structure.
- Before: send a short agenda, including any decisions you need.
- During: one person takes notes; note every decision and every action item, with who will do it.
- After: send the notes, so everyone remembers the same thing.
๐ป Hold a five-minute stand-up with your team (each person: done, next,
blocked). Write the notes in standup.md.
Deliverables
๐ป Add a section on communication to your team's NORMS.md:
- Where do questions go (chat, issues, meetings)? How quickly do we respond?
- When do we ask for help?
- How do we review and disclose AI-drafted messages, especially to clients?
- Note: The bug in
buggy/shifts.pyis that overnight shifts (for example, 22:00 to 02:00) count as negative hours.- Proposal: Introduce this lab right before the first client check-in.