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.
If it has a URL, link to it
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
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.
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