Skip to content

Collaboration Tools & Infrastructure

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

Overview

This directory contains templates, processes, and guidelines for team collaboration and coordination. Even solo developers need this infrastructure for their "future self" and eventual team growth.

Goal: Enable effective async-first collaboration while maintaining code quality, knowledge sharing, and team cohesion.

Directory Structure

03_12_00_communication_setup/

Purpose: How team communicates and coordinates

Key files: - Communication matrix (what tool for what purpose) - Slack configuration and best practices - Discord setup for audio development teams - Webhook integrations (GitHub, CI/CD, monitoring)

Use when: Setting up team communication infrastructure

03_12_01_project_management/

Purpose: Track work, plan sprints, manage projects

Key files: - Linear setup guide (paid, powerful) - GitHub Projects guide (free alternative) - Estimation guidelines (story points, velocity) - Issue templates (bug report, feature request, technical spike)

Use when: Need to organize and track development work

03_12_02_review_workflows/

Purpose: Code review process and best practices

Key files: - Pull request template - Review checklist (comprehensive) - Review etiquette (how to give/receive feedback) - Approval process (merge requirements)

Use when: Establishing or improving code review culture

03_12_03_knowledge_sharing/

Purpose: Organize and share team knowledge

Key files: - Wiki structure and organization - ADR template (cross-reference to decision tracking) - Troubleshooting guide template - Meeting notes template

Use when: Building team knowledge base

03_12_04_onboarding_process/

Purpose: Ramp up new team members quickly

Key files: - Onboarding checklist (Day 1 → Month 3) - Buddy system guide (mentoring structure) - Good first tasks (building confidence) - Cultural guide (team values and norms)

Use when: Hiring and onboarding new team members

03_12_05_decision_tracking/

Purpose: Document and track important decisions

Key files: - ADR template and example (Architecture Decision Records) - Decision log template (lighter weight) - RFC process (Request for Comments for major proposals) - Retrospective format (sprint improvement process)

Use when: Making and documenting significant decisions

Quick Start Guides

Solo Developer

You still need collaboration infrastructure for your future self:

  1. Minimal setup:
  2. GitHub Issues for task tracking
  3. ADRs for major decisions (when they happen)
  4. Keep a daily notes file

  5. Basic README documentation

  6. Nice to have:

  7. GitHub Projects kanban board
  8. Automated CI/CD notifications (email)
  9. Decision log for smaller choices

Small Team (2-5 people)

  1. Communication (Week 1):
  2. Choose: Slack (paid, enterprise) or Discord (free, audio-friendly)
  3. Set up essential channels
  4. Define response time expectations

  5. Configure GitHub webhooks

  6. Project Management (Week 2):

  7. Choose: GitHub Projects (free) or Linear (paid, $8/user)
  8. Create basic workflow (Backlog → Todo → In Progress → Review → Done)
  9. Set up issue templates

  10. Plan first sprint (2 weeks)

  11. Code Review (Week 3):

  12. Define PR requirements (1 approval, tests pass)
  13. Use PR template
  14. Train team on review etiquette

  15. Set response time target (< 24h)

  16. Knowledge Sharing (Week 4):

  17. Start ADRs for major decisions
  18. Create basic wiki structure
  19. Document first troubleshooting guides
  20. Keep meeting notes

Growing Team (5-15 people)

Do everything above, plus:

  1. Communication:
  2. Project-specific channels
  3. User groups/roles for @mentions
  4. On-call rotation and alerts

  5. No-meeting time blocks

  6. Project Management:

  7. Full Linear/GitHub Projects setup
  8. Estimation and velocity tracking
  9. Roadmap planning (quarterly)

  10. Multiple project boards

  11. Code Review:

  12. CODEOWNERS file (auto-assign reviewers)
  13. Review rotation (spread knowledge)
  14. Pair programming sessions

  15. Architecture review group

  16. Onboarding:

  17. Formal onboarding checklist
  18. Buddy system
  19. Good first issue backlog

  20. Cultural documentation

  21. Decision Tracking:

  22. RFC process for major changes
  23. ADR index and organization
  24. Sprint retrospectives
  25. Quarterly process reviews

Core Principles

1. Async-First Communication

  • Default to written communication (Slack, GitHub, docs)
  • Respect deep work time (no expectation of immediate response)
  • Document decisions (don't lose them in chat)
  • Meetings are exception, not default

Why: Enables distributed teams, respects focus time, creates searchable history

2. Documentation-Heavy

  • Write it down (decisions, processes, architecture)
  • Keep it current (outdated docs worse than no docs)
  • Make it discoverable (clear structure, good search)
  • Link liberally (connect related information)

Why: Institutional knowledge, onboarding, prevents re-litigating

3. Tool-Agnostic

  • Define processes, not tools (works with Slack, Discord, Teams, etc.)
  • Choose tools intentionally (team consensus, needs-based)
  • Tools serve process, not vice versa
  • Be willing to change (if tool isn't working)

Why: Flexibility, avoid vendor lock-in, focus on principles

4. Quality Over Speed

  • Code reviews are thorough (not rubber-stamping)
  • Tests are required (not optional)
  • Refactor when needed (don't accumulate debt)
  • Ship working software (not "fix it later")

Why: Long-term velocity, maintainability, team sanity

5. Kindness & Respect

  • Be kind in reviews (critique code, not people)
  • Assume good intent (people make mistakes)
  • Disagree respectfully (focus on what's best)
  • Celebrate successes (recognize good work)

Why: Psychological safety, team cohesion, retention

Implementation Roadmap

Month 1: Foundation

  • Choose communication platform (Slack/Discord)
  • Set up GitHub repository
  • Configure basic GitHub Actions (CI)
  • Create first ADR (technology choices)
  • Write initial README

Month 2: Processes

  • Define code review workflow
  • Set up project management (Linear/GitHub Projects)
  • Create issue templates
  • First sprint (2 weeks)
  • First retrospective

Month 3: Documentation

  • Start team wiki
  • Document architecture (high-level)
  • Create troubleshooting guides
  • Onboarding checklist (if hiring)
  • Cultural guide

Month 4+: Refinement

  • Review and iterate on processes
  • Automate what can be automated
  • Scale processes as team grows
  • Regular retrospectives and improvements

Metrics to Track

Communication Health

  • Response time (by priority): P0 < 15min, P1 < 2h, P2 < 24h
  • Decisions documented: 100% of architectural decisions in ADRs
  • Meeting hours/week: < 5 hours (async-first working)

Code Review Health

  • Review time: Average < 24 hours to first review
  • Approval rate: 50-70% approved first review (not too lenient/strict)
  • PR size: Average < 400 lines (reviewable in < 30 min)

Onboarding Health

  • Time to first PR: < 3 days
  • Time to productivity: < 1 month
  • Retention: New hires stay > 1 year

Knowledge Health

  • Doc freshness: Reviewed quarterly
  • Search success: Can find info in < 5 minutes
  • ADR coverage: All major decisions documented

Common Challenges

Challenge 1: Too Much Process

Symptom: Team complains about bureaucracy, process slowing down shipping

Solution: - Audit processes quarterly - Remove what's not adding value - Automate repetitive tasks - Trust team more, gatekeep less

Challenge 2: Not Enough Process

Symptom: Chaos, lost decisions, unclear ownership, frequent miscommunication

Solution: - Start with minimums (communication matrix, code review, ADRs) - Add incrementally based on pain points - Document as you go - Iterate in retrospectives

Challenge 3: Process Drift

Symptom: Documented processes don't match reality

Solution: - Quarterly review of documentation - Update docs or change practice (pick one) - Make docs easy to update - Assign owners to key docs

Challenge 4: Low Engagement

Symptom: People don't participate in retros, reviews, discussions

Solution: - Make meetings optional (trust team) - Rotate facilitation (spread ownership) - Act on feedback (show it matters) - Keep meetings short and valuable

Challenge 5: Information Overload

Symptom: Too many channels, notifications, meetings; can't keep up

Solution: - Consolidate channels (fewer, better-organized) - Clear notification policies (what requires immediate attention) - Async default (reduce synchronous pressure) - No-meeting blocks (protect focus time)

Customization Guide

These templates are starting points. Adapt to your team:

Small Adjustments

  • Change terminology (sprint → cycle, ADR → decision doc)
  • Adjust response times (based on team size, timezone spread)
  • Modify issue templates (add/remove sections)
  • Choose different tools (Slack vs Discord, Linear vs GitHub Projects)

Major Adaptations

  • Industry-specific (embedded, game dev, web)
  • Company culture (startup vs enterprise)
  • Team structure (centralized vs distributed)
  • Regulatory requirements (compliance, security)

Key: Preserve principles (async-first, documented, kind), change details

Resources

External Resources

Internal Resources (This Repo)

Contributing

Found a better practice? Have a template improvement? Please contribute!

  1. Test the change with your team
  2. Document why it's better
  3. Create PR with update
  4. Share learnings in description

We learn from each other.

Support

Questions about these processes? - Communication: See communication_matrix.md - Onboarding: See onboarding_checklist.md - Decisions: See adr_template.md

Remember: Process should enable great work, not prevent it. Start simple, iterate based on real needs, and always optimize for team happiness and productivity.