Professional communication

Lab setup

First, make sure you have completed the initial setup.

If you are part of a course

  1. Open Terminal. Run the update command to make sure you have the latest code.
    $ mwc update
  2. Move to this lab's directory.
    $ cd ~/Desktop/making_with_code/pilot/labs/lab_professional_comms
    

If you are working on your own

  1. Move to your MWC directory.
    $ cd ~/Desktop/making_with_code
    
  2. 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:

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:

๐Ÿ‘ 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:

๐Ÿ’ป 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:

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:

๐Ÿ’ป 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:

๐Ÿ’ป 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:

  1. Check every factual claim. Is it true? Do you know it's true?
  2. Cut what you don't mean.
  3. Make sure you could explain every sentence if someone asked.
  4. 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.

๐Ÿ’ป 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: