Communication Setup

Philosophy: Async-first, documentation-heavy, tool-agnostic

Overview

This directory contains configuration templates and guidelines for setting up team communication infrastructure. The goal is to enable effective collaboration while respecting deep work time, timezone differences, and minimizing context switching.

Core Principles

1. Async-First: Synchronous meetings are the exception, not the default
2. Documentation-Heavy: Decisions are written down, not lost in chat
3. Tool-Agnostic: Define processes, not specific tools (works with Slack, Discord, Teams, etc.)
4. Discoverable: Information findable in < 5 minutes
5. Low-Friction: Tools facilitate work, don't impede it

Files in This Directory

communication_matrix.md

Purpose: Defines what communication channel to use for what purpose

Key sections: - Communication channels by purpose (urgent, daily updates, decisions, etc.) - Response time expectations (P0-P3 priority levels) - Tool comparison matrix (Slack vs Discord vs alternatives) - Communication guidelines (async writing, feedback, questions) - Meeting policies (when sync is appropriate) - Information hierarchy (Git → Wiki → Issues → Chat)

Use when: - Setting up new team communication - Onboarding new members - Team unsure what channel to use - Resolving communication problems

slack_configuration.md

Purpose: Complete Slack workspace setup guide

Key sections: - Channel structure (core, project, domain, meta, social) - Channel naming conventions - Roles and user groups - Essential integrations (GitHub, CI/CD, monitoring) - Bots (Geekbot, Donut, Polly) - Notification settings recommendations - Etiquette and best practices - Cost optimization

Use when: - Setting up new Slack workspace - Migrating to Slack - Optimizing existing Slack setup - Team > 5 people needing formal communication

discord_setup.md

Purpose: Discord server configuration for development teams

Key sections: - Why Discord for audio development (voice quality, free tier) - Server structure (categories and channels) - Roles and permissions - Voice channel configuration (audio testing, focus rooms) - Bots and integrations - Server boosts for better audio quality - Community features (events, forums)

Use when: - Team prefers Discord over Slack - Need high-quality voice communication - Budget-conscious (free tier is generous) - Community-focused team culture

webhooks_config.json

Purpose: Technical webhook configuration reference

Key sections: - GitHub Actions notifications (CI/CD, deployments) - Pull request notifications - Prometheus alert routing - Linear/project management integrations - Webhook security (signature verification, rate limiting) - Monitoring and metrics - Setup instructions for each platform - Best practices

Use when: - Automating notifications from CI/CD - Integrating monitoring alerts - Connecting project management tools - Setting up custom automations

Quick Start

For Solo Developers

You still need communication infrastructure for your "future self":

1. Minimal setup:
2. Use GitHub Issues for task tracking
3. Write ADRs for major decisions
4. Keep a daily notes file (YYYY-MM-DD.md)

5. Set up CI/CD notifications (email is fine)

6. As you grow:

7. Add Slack/Discord when team > 2 people
8. Implement standup automation when team > 3
9. Add project channels when team > 5

For Small Teams (2-5 people)

1. Read communication_matrix.md
2. Choose platform: Slack or Discord (see comparison below)
3. Follow relevant setup guide
4. Configure essential integrations (GitHub, CI/CD)
5. Set up async standups
6. Pin communication matrix in general channel

For Growing Teams (5-15 people)

1. Complete small team setup
2. Add project-specific channels
3. Implement user groups/roles for mentions
4. Set up dedicated monitoring channels
5. Create meeting policies (no-meeting blocks)
6. Establish on-call rotation and alerts
7. Add moderation roles

For Distributed Teams

1. Complete growing team setup
2. Emphasize async communication even more
3. Record all meetings for timezone-shifted members
4. Use async standups (Geekbot/Standup bot)
5. Clear response time expectations by priority
6. Documentation is source of truth, not chat

Slack vs Discord Comparison

Factor	Slack	Discord
Best for	Enterprise, formal teams	Communities, casual teams
Cost	Free: 90 days history, 10 integrations Paid: $8/user/month	Free: unlimited history Nitro: $10/month individual
Integrations	Extensive enterprise integrations	Growing, gaming-focused
Voice quality	Good (screen share quality varies)	Excellent (up to 384kbps with boosts)
Search	Excellent	Good
Mobile	Excellent	Excellent
Threads	Excellent	Good (improving)
Formality	Professional	Casual
Learning curve	Low	Low

Recommendation: - Slack: Enterprise teams, need enterprise integrations, formal culture - Discord: Audio-focused teams (voice quality!), budget-conscious, community feel - Either: Both work well, choose based on team preference

Common Patterns

Pattern 1: GitHub-Centric

Code reviews: GitHub PR comments
Issues/tasks: GitHub Issues
Decisions: ADRs in Git
Daily sync: Slack/Discord async standup
Urgent: Slack/Discord #urgent channel
Social: Slack/Discord #random

Pros: Centralized in GitHub, familiar workflow Cons: GitHub not great for real-time discussion

Pattern 2: Linear-Centric

Code reviews: GitHub PR comments
Issues/tasks: Linear (synced to GitHub)
Decisions: ADRs in Git
Project updates: Linear → Slack integration
Daily sync: Slack/Discord async standup
Urgent: Slack/Discord #urgent channel

Pros: Better project management UX Cons: Another tool to learn, costs money

Pattern 3: All-Async

Code reviews: GitHub PR comments
Issues/tasks: GitHub Issues
Decisions: ADRs in Git
Daily sync: Written notes in shared doc
Team updates: Weekly email digest
Discussions: GitHub Discussions

Pros: Maximum async, minimal tools Cons: Harder to build team cohesion

Recommendation: Start with Pattern 1, move to Pattern 2 if team > 10

Integration Guide

Essential Integrations (Priority 1)

1. GitHub → Chat: PR notifications, build status
2. CI/CD → Chat: Build failures, deployment status
3. Monitoring → Chat: Critical alerts

Nice-to-Have Integrations (Priority 2)

1. Project Management → Chat: Issue updates, sprint planning
2. Calendar → Chat: Meeting reminders
3. Standup Bot: Async daily updates

Optional Integrations (Priority 3)

1. Error tracking: Sentry, Rollbar alerts
2. Analytics: Usage metrics, dashboards
3. Social: Donut (coffee chats), Giphy (fun)

Setup order: Start with Priority 1, add others as needed

Anti-Patterns to Avoid

❌ Chat as source of truth: Important decisions must be documented ❌ Too many channels: Create channel only when clear need ❌ No response expectations: Define SLAs for each priority ❌ Meetings without agenda: Always share agenda 24h before ❌ Notification spam: Configure integrations to filter noise ❌ Synchronous by default: Assume async unless proven otherwise ❌ No moderation: Define rules and enforce them consistently ❌ Zombie channels: Archive inactive channels (no activity 30 days)

Troubleshooting

Problem: Too many notifications

Symptoms: Constant interruptions, alert fatigue Solutions: - Audit channel subscriptions, mute low-priority - Set notification schedule (e.g., 9am-6pm only) - Change to "mentions only" for most channels - Use Do Not Disturb during focus time - Filter integration noise (only failures, not successes)

Problem: Important info gets lost in chat

Symptoms: Decisions re-litigated, context lost, searching for links Solutions: - Implement ADR process for decisions - Pin important messages in channels - Use threads to keep conversations organized - Move important discussions to documentation - Create wiki pages for frequently asked questions

Problem: No response to questions

Symptoms: Questions ignored, long wait times, duplicated effort Solutions: - Set clear response time expectations (see communication matrix) - Use user group mentions for teams (@team-dev) - Escalate after reasonable wait (4h → mention, 24h → DM) - Assign channel moderators to monitor - Reward helpful responses (kudos, recognition)

Problem: Timezone conflicts

Symptoms: Meetings scheduled at bad times, async updates misaligned Solutions: - Use absolute times with timezone (not "tomorrow") - Rotate meeting times to share pain - Record all meetings for async viewing - Embrace async-first culture even more - Use "no meeting" blocks for overlap time

Problem: Tool fatigue

Symptoms: Too many tools, confusion where to post, duplication Solutions: - Consolidate tools (do you really need 5?) - Create clear communication matrix - Cross-link between tools (don't duplicate content) - Choose fewer, better-integrated tools - Onboard team properly on remaining tools

Metrics to Track

Communication Health

• Average response time by priority level
• % of decisions documented in ADRs
• Channel activity (identify zombie channels)
• Meeting hours per week (should be minimal)
• Documentation updates per week

Tool Usage

• Daily active users
• Messages per channel (identify noise)
• Integration success rate (webhooks)
• Search queries (what are people looking for?)

Team Health

• Participation rate in standups
• Code review response time
• Onboarding time to first contribution
• Survey: Communication satisfaction

Review: Monthly, adjust policies as needed

Evolution Path

Stage 1: Solo → Small Team (1-5 people)

• Add chat platform
• Setup GitHub integration
• Async standup
• Weekly sync meeting

Stage 2: Growing Team (5-15 people)

• Add project channels
• Implement user groups
• Define on-call rotation
• Meeting policies (no-meeting times)
• Moderation roles

Stage 3: Scaling Team (15-50 people)

• Department channels
• Advanced automation
• Analytics and metrics
• Dedicated community manager
• Multiple timezones support

Stage 4: Large Organization (50+ people)

• Enterprise SSO
• Compliance policies
• Advanced security
• Multiple workspaces/servers
• Professional moderation team

Next Steps

1. Review: Read communication_matrix.md with team
2. Decide: Choose platform (Slack, Discord, or alternative)
3. Setup: Follow relevant configuration guide
4. Integrate: Configure essential webhooks (GitHub, CI/CD)
5. Onboard: Train team on communication norms
6. Iterate: Review monthly, adjust as needed

Related Documentation

• Project Management Templates
• Review Workflows
• Knowledge Sharing
• Onboarding Process
• Decision Tracking

Resources

• Async Communication Guide - GitLab
• Slack Best Practices
• Discord Community Guidelines
• Webhook Security Best Practices

---

Remember: Tools serve the process, not vice versa. Start simple, iterate based on real team needs.