Project Decisions in NoteVault | Knowledge Hub
Use GitScrum NoteVault to capture project decisions, meeting notes, and institutional knowledge. Centralized, searchable, and linked to tasks.
7 min read
Project decisions, meeting outcomes, and key discussions often live in scattered emails, Slack threads, and people's memories. NoteVault centralizes this knowledge, links it to relevant tasks and projects, and makes it searchable for the entire team.
NoteVault Benefits
| Scattered Documentation | With NoteVault |
|---|---|
| Lost in email | Centralized, searchable |
| Slack thread buried | Linked to context |
| Meeting notes in gdoc | Integrated with tasks |
| Tribal knowledge | Documented and shared |
| "Ask Sarah" | Self-service answers |
NoteVault Organization
Recommended Structure
NOTEVAULT ORGANIZATION
══════════════════════
📁 PROJECTS
├── Project Alpha
│ ├── 📄 Project Charter
│ ├── 📄 Technical Architecture
│ ├── 📄 API Design Decisions
│ └── 📁 Meeting Notes
│ ├── 📄 Kickoff - Jan 5
│ ├── 📄 Sprint Review - Jan 19
│ └── 📄 Stakeholder Sync - Jan 26
│
├── Project Beta
│ ├── 📄 Requirements
│ ├── 📄 Design Decisions
│ └── 📁 Research
│ ├── 📄 Competitor Analysis
│ └── 📄 User Interview Summary
📁 TEAM
├── 📄 Team Charter
├── 📄 Working Agreements
├── 📄 On-call Runbooks
└── 📄 Onboarding Checklist
📁 TECHNICAL
├── 📄 Architecture Overview
├── 📄 Coding Standards
├── 📄 Deployment Guide
└── 📁 ADRs
├── 📄 ADR-001: Database Choice
└── 📄 ADR-002: API Design
Note Types
DOCUMENT TYPES TO CREATE
════════════════════════
DECISION RECORDS:
─────────────────────────────────────
Purpose: Capture why decisions were made
Template:
├── Context: What was the situation?
├── Decision: What did we decide?
├── Alternatives: What else was considered?
├── Consequences: What are the trade-offs?
└── Date and participants
MEETING NOTES:
─────────────────────────────────────
Purpose: Capture outcomes, not transcripts
Template:
├── Date and attendees
├── Decisions made
├── Action items (linked to tasks)
├── Open questions
└── Next steps
SPECIFICATIONS:
─────────────────────────────────────
Purpose: Define what we're building
Template:
├── Overview
├── Requirements
├── User stories
├── Technical approach
├── Open questions
└── Links to tasks
RUNBOOKS:
─────────────────────────────────────
Purpose: Step-by-step procedures
Template:
├── Purpose
├── Prerequisites
├── Steps
├── Verification
├── Rollback
└── Escalation
Creating Effective Notes
Decision Documentation
DOCUMENTING DECISIONS
═════════════════════
DECISION NOTE TEMPLATE:
─────────────────────────────────────
# Decision: [Title]
**Date:** 2024-01-20
**Participants:** Sarah, Mike, Alex
**Status:** Decided
## Context
We needed to decide how to handle user authentication
for the mobile app. Key considerations:
- Security requirements
- User experience
- Development effort
- Maintenance burden
## Decision
Use OAuth 2.0 with refresh tokens, implementing our
own auth server rather than third-party service.
## Alternatives Considered
### Firebase Auth
- Pros: Quick to implement, managed service
- Cons: Vendor lock-in, limited customization
- Rejected: Need custom claims for our permission model
### Auth0
- Pros: Feature-rich, good docs
- Cons: Cost at scale, external dependency
- Rejected: Pricing prohibitive at our user volume
## Consequences
- (+) Full control over auth flow
- (+) No external dependencies
- (-) More initial development effort
- (-) Ongoing maintenance responsibility
## Related
- [[Task GS-456: Implement auth server]]
- [[Note: API Security Standards]]
─────────────────────────────────────
LINKING:
├── Link to implementation task
├── Link to related decisions
├── Tag with #decision
└── Add to project space
Meeting Notes
EFFECTIVE MEETING NOTES
═══════════════════════
MEETING NOTE TEMPLATE:
─────────────────────────────────────
# Sprint Planning - Jan 20, 2024
**Attendees:** Team + PO
**Duration:** 1 hour
## Key Decisions
1. Prioritizing auth work over dashboard
2. Deferring analytics to next sprint
3. Adding buffer for unexpected bugs
## Committed Work
- GS-123: Login API (M) - Sarah
- GS-124: Password reset (S) - Mike
- GS-125: Session management (M) - Alex
- GS-126: Bug fixes buffer (S) - Team
Total: 21 points (capacity: 25)
## Action Items
- [ ] [[GS-127]]: Sarah to create auth docs
- [ ] [[GS-128]]: Mike to set up test accounts
- [ ] PM to update stakeholders on analytics delay
## Open Questions
- Token expiry duration TBD (security review)
- Mobile app timeline depends on API completion
## Next Meeting
Sprint Review - Feb 2, 2024
─────────────────────────────────────
TIPS:
├── Focus on outcomes, not discussion
├── Link action items to tasks
├── Keep concise (1 page max)
└── Send summary after meeting
NoteVault Features
Linking and References
NOTEVAULT LINKING
═════════════════
LINK TO TASKS:
├── [[GS-123]] - Links to task
├── Auto-displays task title
├── Click to navigate
└── Bidirectional (task shows linked notes)
LINK TO NOTES:
├── [[Note Title]] - Links to note
├── Creates connection
├── Backlinks shown on linked note
└── Build knowledge graph
LINK TO PROJECTS:
├── Add note to project space
├── Visible in project overview
├── Access controlled by project
└── Context always clear
TAGS:
├── #decision - Filter decisions
├── #meeting - Filter meeting notes
├── #adr - Architecture decisions
└── #runbook - Operational docs
Search and Discovery
FINDING NOTES
═════════════
FULL-TEXT SEARCH:
├── Search all note content
├── Filter by tag
├── Filter by project
├── Filter by date
└── Filter by author
NAVIGATION:
├── Project → Notes in project
├── Task → Linked notes
├── Note → Backlinks
├── Tag → All tagged notes
└── Recent → Recently viewed
EXAMPLES:
├── "authentication decision"
├── #adr database
├── project:alpha meeting
├── author:sarah
└── created:last-week
Workflow Integration
Task-Note Workflow
INTEGRATING NOTES WITH TASKS
════════════════════════════
BEFORE STARTING TASK:
├── Check linked notes for context
├── Review related decisions
├── Find specifications
└── Understand the "why"
DURING TASK:
├── Update notes with learnings
├── Document obstacles encountered
├── Link to new decisions made
└── Add to knowledge base
AFTER TASK:
├── Document final approach
├── Update related notes
├── Create notes for future reference
└── Link from task to notes
EXAMPLE FLOW:
1. Task: "Implement caching layer"
2. Check linked note: "ADR-007: Cache Strategy"
3. Find related: "Redis Setup Guide"
4. Work on task
5. Document: "Caching Gotchas" for next person
6. Link new note to task
Best Practices
For NoteVault Usage
Anti-Patterns
DOCUMENTATION MISTAKES:
✗ Writing once, never updating
✗ No links to related content
✗ Too much detail (unreadable)
✗ Too little detail (unhelpful)
✗ Duplicating across tools
✗ Private notes for public knowledge
✗ No organization structure
✗ Orphaned notes with no links