Better team communication

A few small rules for communicating with teammates while working on software & design projects.

Prefer asynchronous communication

Multi-tasking doesn’t actually work well.

Fully dedicating to a task will produce better & faster results.

Async communication prevents interruptions for dedicated tasks.

Wisely use face-to-face time

Write an Issue or it won’t get done.

Decisions shouldn’t be made in person—people need time to think.

Tasks shouldn’t be assigned in person—people will forget.

Reserve face-to-face communication for engaging with people: brainstorming, personal feedback, etc.

Nobody gets fired for opening an Issue

Issue or it doesn’t exist.

  • Have a question? Open an Issue.
  • Have an idea? Open an Issue.
  • Something wonky? Open an Issue.

Issues are cheap, easy, permanent, searchable & linkable.

Be mindful of noise

Too many notifications is distracting.

Contribute to Issues you can make in impact on—avoid drive-by comments.

Only comment if you have something to add—use “reactions” for support.

Always provide context in Issues, Pull requests & Commits: “A few edits” isn’t enough information.

Use checklists to make blockers explicit

Being obvious is always better.

If an Issue is blocked, use todo lists to mention the reasons—and whom.

Issues are organization-wide todos

Don’t close an Issue until it’s resolved.

Issues are a task that needs to be completed or a placeholder for a task.

Make Issues active: use a verb in the title.

Long-lasting Issues are completely okay if they still need to be completed.

Keep discussions logically distinct

Don’t dump everything into a single Issue.

Keep Issues as focused as possible—one single purpose.

If a concern enters the Issue’s discussion that’s not directly related, open a new Issue and guide people there.

It’s your obligation to find the URL.

People are busy, they shouldn’t have to dig around for the URL of the thing you’re talking about.

Make changes with pull requests

Pull request or it won’t get changed.

Everything should be reviewed by a peer before entering the master branch.

Create a pull request early to get feedback right away.

Pull requests are team property: the code isn’t yours it’s everybody’s to make better.

Be professional

Polite, courteous, honest.

  • Use well constructed sentences
  • Remind people gently
  • Don’t ping, just ask politely
  • Overcompensate for tone
  • Be human

Inspired & tweaked from “15 rules for communicating at GitHub”.
© 2016 Ben Balter