Knowledge Base with NoteVault | Team Documentation
Build a team knowledge base with GitScrum NoteVault. Capture architecture decisions, onboarding guides, runbooks, and institutional knowledge in one place.
7 min read
A well-organized knowledge base prevents knowledge silos and speeds up onboarding. GitScrum's NoteVault feature provides a centralized space for documentation, decisions, and institutional knowledge that stays connected to your project work.
Knowledge Base Value
Why Document
KNOWLEDGE BASE BENEFITS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ WITHOUT KNOWLEDGE BASE: │
│ │
│ • "Ask Sarah, she knows how that works" │
│ • Same questions answered repeatedly │
│ • Knowledge leaves when people leave │
│ • Onboarding takes months │
│ • Decisions forgotten, repeated, or contradicted │
│ │
│ WITH KNOWLEDGE BASE: │
│ │
│ • "Check the docs, it's documented" │
│ • Self-service answers │
│ • Knowledge persists beyond individuals │
│ • Faster onboarding │
│ • Decision history preserved │
│ │
│ ROI EXAMPLE: │
│ │
│ New hire questions: 10/week │
│ Time per answer: 15 minutes │
│ Weekly cost: 2.5 hours of senior dev time │
│ │
│ With good docs: 80% reduction │
│ Savings: 2 hours/week = 100 hours/year │
│ Plus: Faster new hire productivity │
└─────────────────────────────────────────────────────────────┘
What to Document
DOCUMENTATION CATEGORIES:
┌─────────────────────────────────────────────────────────────┐
│ │
│ ONBOARDING: │
│ • Getting started guide │
│ • Environment setup │
│ • Who's who │
│ • Key processes overview │
│ • First week checklist │
│ │
│ ARCHITECTURE: │
│ • System overview │
│ • Service map │
│ • Data flow diagrams │
│ • Technology choices (and why) │
│ • Architecture Decision Records (ADRs) │
│ │
│ PROCESSES: │
│ • Development workflow │
│ • Code review process │
│ • Release process │
│ • Incident response │
│ • How we do sprints │
│ │
│ RUNBOOKS: │
│ • Deploy procedures │
│ • Common issues and fixes │
│ • Monitoring alerts and responses │
│ • Rollback procedures │
│ │
│ DECISIONS: │
│ • Major technical decisions │
│ • Process changes │
│ • Tool selections │
│ • Policy decisions │
└─────────────────────────────────────────────────────────────┘
NoteVault Structure
Organization
KNOWLEDGE BASE STRUCTURE:
┌─────────────────────────────────────────────────────────────┐
│ NoteVault │
├─────────────────────────────────────────────────────────────┤
│ │
│ 📁 Onboarding │
│ ├── Welcome to the team │
│ ├── Environment setup │
│ ├── Codebase overview │
│ ├── First week checklist │
│ └── Key contacts │
│ │
│ 📁 Architecture │
│ ├── System overview │
│ ├── Services directory │
│ ├── Database schema │
│ └── 📁 ADRs │
│ ├── ADR-001: Use GraphQL for API │
│ ├── ADR-002: PostgreSQL as primary DB │
│ └── ADR-003: Kubernetes deployment │
│ │
│ 📁 Development │
│ ├── Coding standards │
│ ├── Git workflow │
│ ├── Code review guidelines │
│ └── Testing requirements │
│ │
│ 📁 Operations │
│ ├── Deploy process │
│ ├── Monitoring setup │
│ ├── Incident response │
│ └── 📁 Runbooks │
│ ├── Database failover │
│ └── Cache clear procedure │
│ │
│ 📁 Team │
│ ├── Meeting notes │
│ ├── Retrospective outcomes │
│ └── Team agreements │
└─────────────────────────────────────────────────────────────┘
Document Templates
ARCHITECTURE DECISION RECORD:
┌─────────────────────────────────────────────────────────────┐
│ # ADR-004: Frontend State Management │
│ │
│ **Status:** Accepted │
│ **Date:** 2024-01-15 │
│ **Deciders:** @alex, @maria, @jordan │
│ │
│ ## Context │
│ Our React application needs consistent state management │
│ as it grows. Currently mixing local state, context, and │
│ prop drilling inconsistently. │
│ │
│ ## Decision │
│ Adopt Zustand for global state management. │
│ │
│ ## Options Considered │
│ 1. Redux - Full-featured but verbose │
│ 2. Zustand - Simple, minimal boilerplate ✅ (chosen) │
│ 3. Jotai - Atomic approach, newer │
│ 4. Context only - Already proving insufficient │
│ │
│ ## Consequences │
│ - Simpler store setup than Redux │
│ - Team needs to learn Zustand patterns │
│ - Migrate existing Context usage over next sprint │
│ │
│ ## Related │
│ - [Task #234: State management migration] │
│ - ADR-002: React adoption │
└─────────────────────────────────────────────────────────────┘
Linking to Work
CONNECTING DOCS TO TASKS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ IN NOTEVAULT DOCUMENT: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ # Deploy Process ││
│ │ ││
│ │ ## Overview ││
│ │ Production deploys happen every Tuesday... ││
│ │ ││
│ │ ## Related Tasks ││
│ │ - [#234: Automate deploy notifications] ││
│ │ - [#267: Add deploy rollback step] ││
│ │ ││
│ │ ## Last Updated ││
│ │ January 15, 2024 by @alex ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ IN TASK DESCRIPTION: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Task #234: Automate deploy notifications ││
│ │ ││
│ │ Add Slack notifications when deploy starts/finishes. ││
│ │ ││
│ │ See: [Deploy Process doc] for current workflow. ││
│ │ ││
│ │ When done: Update the NoteVault doc with new steps. ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ BENEFIT: Context travels with the work │
└─────────────────────────────────────────────────────────────┘
Keeping Docs Current
Maintenance
DOCUMENTATION MAINTENANCE:
┌─────────────────────────────────────────────────────────────┐
│ │
│ OWNERSHIP MODEL: │
│ │
│ Section │ Owner │ Review Cycle │
│───────────────────┼────────────┼──────────────────────────│
│ Onboarding │ @maria │ After each new hire │
│ Architecture │ @alex │ Quarterly │
│ Development │ @jordan │ Quarterly │
│ Operations │ @devops │ Monthly │
│ Team │ Rotates │ As created │
│ │
│ OWNER RESPONSIBILITIES: │
│ • Review assigned sections on schedule │
│ • Update when changes happen │
│ • Archive outdated content │
│ • Respond to questions/feedback │
│ │
│ FRESHNESS INDICATORS: │
│ │
│ 🟢 Updated in last 3 months │
│ 🟡 Updated 3-6 months ago │
│ 🔴 Not updated in 6+ months │
│ │
│ QUARTERLY REVIEW: │
│ • Scan all docs for staleness │
│ • Update or archive outdated content │
│ • Identify gaps │
│ • Assign action items │
└─────────────────────────────────────────────────────────────┘
Documentation Culture
BUILDING DOCUMENTATION HABITS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ MAKE IT EASY: │
│ • Simple editor (Markdown) │
│ • Templates for common doc types │
│ • Quick links to create new docs │
│ • Don't require perfection │
│ │
│ MAKE IT EXPECTED: │
│ • Include "Update docs" in task acceptance criteria │
│ • Ask "Is this documented?" in code reviews │
│ • New decisions → ADR created │
│ • New processes → Runbook created │
│ │
│ MAKE IT VALUED: │
│ • Recognize good documentation in team meetings │
│ • Link to docs rather than re-explaining │
│ • "Check the docs first" as team norm │
│ • Documentation as part of "done" │
│ │
│ DON'T: │
│ ✗ Let one person be "the documenter" │
│ ✗ Require elaborate formatting │
│ ✗ Let docs rot without review │
│ ✗ Duplicate information across docs │
│ ✗ Create docs that only one person understands │
└─────────────────────────────────────────────────────────────┘