Knowledge Management for Dev Teams | ADRs, Docs
Capture and share team knowledge with GitScrum. Document architecture decisions, onboarding guides, and processes where work happens. Reduce onboarding time.
9 min read
Knowledge walks out the door when people leave. GitScrum helps teams document decisions, processes, and learnings where work happens.
Knowledge Types
What to Document
DOCUMENTATION CATEGORIES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ARCHITECTURE & DESIGN: │
│ • System architecture diagrams │
│ • API documentation │
│ • Data models │
│ • Architecture Decision Records (ADRs) │
│ • Technology choices and rationale │
│ │
│ PROCESSES: │
│ • Deployment procedures │
│ • On-call runbooks │
│ • Code review guidelines │
│ • Sprint rituals │
│ • Incident response │
│ │
│ ONBOARDING: │
│ • Setup guides │
│ • Team norms and expectations │
│ • Key contacts and roles │
│ • First week checklist │
│ • Common gotchas │
│ │
│ DECISIONS: │
│ • Why we chose X over Y │
│ • Context that informed decisions │
│ • Trade-offs considered │
│ • When to revisit decisions │
│ │
│ LEARNINGS: │
│ • Post-mortem insights │
│ • Retrospective action items │
│ • Tribal knowledge │
│ • Tips and tricks │
└─────────────────────────────────────────────────────────────┘
Documentation Locations
WHERE KNOWLEDGE LIVES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ IN CODE REPOSITORY: │
│ │
│ /docs │
│ ├── README.md Quick start │
│ ├── CONTRIBUTING.md How to contribute │
│ ├── architecture/ │
│ │ ├── overview.md System architecture │
│ │ └── decisions/ ADRs │
│ │ ├── 001-use-postgres.md │
│ │ └── 002-auth-approach.md │
│ ├── api/ API documentation │
│ └── runbooks/ Operational guides │
│ │
│ IN WIKI/NOTION: │
│ │
│ Team Handbook │
│ ├── Team processes │
│ ├── Meeting schedules │
│ ├── Roles and responsibilities │
│ └── Onboarding guide │
│ │
│ IN GITSCRUM: │
│ │
│ • Task context and requirements │
│ • Discussion history │
│ • Decision rationale │
│ • Links to relevant docs │
│ │
│ PRINCIPLE: │
│ Technical docs → near code │
│ Process docs → shared wiki │
│ Task context → GitScrum │
└─────────────────────────────────────────────────────────────┘
Architecture Decision Records
ADR Format
ARCHITECTURE DECISION RECORD:
┌─────────────────────────────────────────────────────────────┐
│ ADR-002: Use PostgreSQL for Primary Database │
├─────────────────────────────────────────────────────────────┤
│ │
│ STATUS: Accepted │
│ DATE: 2024-01-15 │
│ AUTHORS: @alex, @maria │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ CONTEXT: │
│ We need a primary database for user data, projects, and │
│ tasks. Expect 100K users in year one, 1M by year three. │
│ Team has experience with both MySQL and PostgreSQL. │
│ │
│ DECISION: │
│ We will use PostgreSQL as our primary database. │
│ │
│ RATIONALE: │
│ • Better JSON support for flexible schemas │
│ • Superior full-text search capabilities │
│ • Strong ACID compliance │
│ • Good performance at our expected scale │
│ • Team familiarity │
│ │
│ ALTERNATIVES CONSIDERED: │
│ │
│ MySQL: │
│ • Pro: Slightly more team experience │
│ • Con: Weaker JSON support │
│ • Con: Need separate search solution │
│ │
│ MongoDB: │
│ • Pro: Flexible schema │
│ • Con: Eventual consistency concerns │
│ • Con: Less team experience │
│ │
│ CONSEQUENCES: │
│ • Need PostgreSQL hosting (RDS) │
│ • Team training on Postgres-specific features │
│ • Can leverage JSONB for extensible fields │
│ │
│ REVIEW DATE: 2025-01-15 (or at 500K users) │
└─────────────────────────────────────────────────────────────┘
When to Write ADRs
ADR TRIGGER POINTS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ WRITE AN ADR WHEN: │
│ │
│ TECHNOLOGY CHOICES: │
│ • Selecting a database │
│ • Choosing a framework │
│ • Adopting a new service │
│ • Picking a vendor │
│ │
│ ARCHITECTURAL PATTERNS: │
│ • Microservices vs monolith │
│ • API design approach │
│ • Authentication strategy │
│ • Caching approach │
│ │
│ SIGNIFICANT CHANGES: │
│ • Rewriting a major component │
│ • Changing deployment strategy │
│ • Modifying data model significantly │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ DON'T WRITE ADR FOR: │
│ │
│ • Minor library choices │
│ • Easily reversible decisions │
│ • Implementation details │
│ • Obvious choices │
│ │
│ GITSCRUM INTEGRATION: │
│ Create ADR task when significant decision needed │
│ Link ADR to related feature work │
│ Include in Definition of Done for architecture changes │
└─────────────────────────────────────────────────────────────┘
Onboarding Documentation
New Member Guide
ONBOARDING DOCUMENTATION:
┌─────────────────────────────────────────────────────────────┐
│ │
│ DAY 1 SETUP GUIDE: │
│ │
│ ☐ ACCOUNTS │
│ • GitHub access: [Request link] │
│ • Slack: Join #team-eng, #announcements │
│ • GitScrum: [Invite link] │
│ • Cloud console: Request from @alex │
│ │
│ ☐ LOCAL DEVELOPMENT │
│ • Clone repos: [List] │
│ • Install dependencies: See README │
│ • Environment setup: [Guide link] │
│ • Verify: Run tests │
│ │
│ ☐ FIRST WEEK │
│ • Meet the team (1:1s scheduled) │
│ • Review architecture docs │
│ • Complete "hello world" task │
│ • Shadow on-call for one day │
│ • Ask lots of questions! │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ KEY CONTACTS: │
│ │
│ Manager: @sarah │
│ Buddy: @jordan (first point of contact) │
│ Tech lead: @alex (architecture questions) │
│ Product: @priya (requirements questions) │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ COMMON GOTCHAS: │
│ │
│ • VPN required for staging access │
│ • Run `npm run setup` before first test │
│ • Database seeds: `npm run db:seed` │
│ • If build fails, try clearing node_modules │
└─────────────────────────────────────────────────────────────┘
Keeping Docs Current
Documentation Hygiene
PREVENTING STALE DOCUMENTATION:
┌─────────────────────────────────────────────────────────────┐
│ │
│ STRATEGIES: │
│ │
│ 1. DOCS IN DEFINITION OF DONE │
│ Every feature task: │
│ ☐ Code complete │
│ ☐ Tests pass │
│ ☐ Documentation updated │
│ ☐ PR approved │
│ │
│ 2. ASSIGN DOC OWNERS │
│ README.md → @alex (reviewed quarterly) │
│ Onboarding guide → @jordan (updated monthly) │
│ API docs → Auto-generated from code │
│ │
│ 3. REGULAR AUDITS │
│ Quarterly: Review all docs for accuracy │
│ Check: Last updated dates │
│ Delete: Obsolete documentation │
│ Update: Stale sections │
│ │
│ 4. DOCS NEAR CODE │
│ README in each service repo │
│ Comments in complex code │
│ API docs generated from code │
│ Changes together = less drift │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ QUARTERLY DOC AUDIT TASK: │
│ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ DOC-Q1: Documentation Quarterly Review ││
│ │ ││
│ │ ☐ Review onboarding guide ││
│ │ ☐ Check architecture diagrams ││
│ │ ☐ Verify runbooks still accurate ││
│ │ ☐ Delete obsolete pages ││
│ │ ☐ Update last-reviewed dates ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Knowledge Capture
From Tasks to Knowledge
GITSCRUM AS KNOWLEDGE SOURCE:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TASK CONTEXT BECOMES KNOWLEDGE: │
│ │
│ WELL-DOCUMENTED TASK: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ PROJ-123: Implement Rate Limiting ││
│ │ ││
│ │ Context: ││
│ │ API experiencing abuse, need rate limiting to protect ││
│ │ infrastructure. ││
│ │ ││
│ │ Decision: ││
│ │ Using Redis + sliding window algorithm. ││
│ │ Considered token bucket but sliding window better ││
│ │ for our burst patterns. ││
│ │ ││
│ │ Implementation notes: ││
│ │ • 100 requests/minute per API key ││
│ │ • Headers indicate remaining quota ││
│ │ • Bypass for internal services via header ││
│ │ ││
│ │ Related PR: #456 ││
│ │ Follow-up: Create ADR for rate limiting approach ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ SEARCHABLE LATER: │
│ "Why did we choose sliding window?" │
│ → Search GitScrum → Find PROJ-123 → See context │
│ │
│ PROMOTE TO PERMANENT DOCS: │
│ Important decisions → ADR │
│ Common procedures → Runbook │
│ Architectural choices → Architecture doc │
└─────────────────────────────────────────────────────────────┘
Retrospective Learnings
CAPTURING RETRO INSIGHTS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ AFTER RETROSPECTIVE: │
│ │
│ 1. DOCUMENT DECISIONS │
│ What we decided to do differently │
│ → Create GitScrum tasks for action items │
│ │
│ 2. UPDATE PROCESSES │
│ If we changed a process │
│ → Update the wiki/handbook │
│ → Communicate change to team │
│ │
│ 3. SHARE LEARNINGS │
│ Insights valuable to others │
│ → Post in engineering channel │
│ → Add to team knowledge base │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ EXAMPLE: │
│ │
│ Retro insight: "PRs sat too long in review" │
│ │
│ Actions: │
│ ☐ Task: Set up PR review SLA notifications │
│ ☐ Doc update: Add review SLA to team handbook │
│ ☐ Process: Add review time to standup │
│ │
│ 3 months later: "Why do we have PR SLAs?" │
│ → Check retro notes → Find the reason │
└─────────────────────────────────────────────────────────────┘