9 min read • Guide 757 of 877
Knowledge Management for Development Teams
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 │
└─────────────────────────────────────────────────────────────┘