Documentation Lives Separately from Tasks and Code

When documentation lives in separate tools from tasks and code, teams waste time searching, context gets lost, and knowledge becomes stale. GitScrum's NoteVault integrates documentation directly with projects and tasks for unified knowledge management.

The Documentation Fragmentation Problem

Scattered documentation creates daily friction:

• Search fatigue — Looking in multiple places for answers
• Stale information — Docs not updated when code changes
• Context loss — No link between docs and related tasks
• Onboarding friction — New developers can't find information
• Duplicate content — Same info written in multiple places

Common Documentation Sprawl

GitScrum NoteVault: Unified Documentation

NoteVault brings documentation into your project workspace:

Features

• Markdown editor — Rich formatting without complexity
• Folder organization — Hierarchical structure per project
• Full-text search — Find anything across all docs
• Task linking — Connect docs to related tasks
• Version history — Track changes over time
• Collaborative editing — Team can update together

Documentation Structure

Organize docs within your project:

Project: Dashboard Redesign
└── NoteVault/
    ├── Architecture/
    │   ├── System Overview
    │   ├── API Design
    │   └── Database Schema
    ├── Guides/
    │   ├── Development Setup
    │   ├── Deployment Process
    │   └── Testing Strategy
    ├── Decisions/
    │   ├── ADR-001: Framework Choice
    │   ├── ADR-002: Auth Strategy
    │   └── ADR-003: State Management
    └── References/
        ├── API Endpoints
        ├── Environment Variables
        └── Third-party Services

Linking Documentation to Tasks

From Task to Documentation

When creating or viewing a task, link to relevant docs:

Task: Implement OAuth login
├── Description: Add Google OAuth support
├── Linked Docs:
│   ├── ADR-002: Auth Strategy
│   ├── API Design > Authentication
│   └── Development Setup > OAuth Config
└── Comments: See linked docs for implementation details

From Documentation to Tasks

Reference tasks within documentation:

## Authentication Implementation

For implementation details, see:
- [Task #234: Implement OAuth login](/project/tasks/234)
- [Task #235: Add session management](/project/tasks/235)

Status: In Progress (Sprint 14)

Documentation Workflows

Architecture Decision Records (ADRs)

Document decisions where they're actionable:

# ADR-002: Authentication Strategy

## Status
Accepted

## Context
We need to implement user authentication for the dashboard.

## Decision
Use OAuth 2.0 with Google as the primary provider.

## Consequences
- Simpler implementation (no password management)
- Dependency on Google availability
- Enterprise SSO can be added later

## Related Tasks
- #234: Implement OAuth login
- #235: Add session management
- #236: Create logout flow

Technical Specifications

Keep specs close to implementation:

# API Specification: User Endpoints

## GET /api/users/:id

Returns user profile data.

### Response
| Field | Type | Description |
|-------|------|-------------|
| id | string | User unique identifier |
| email | string | User email address |
| name | string | Display name |

### Implementation
- Task: #247
- Sprint: 14
- Status: Complete

Onboarding Guides

Living documentation that evolves with the project:

# Developer Onboarding

## Prerequisites
- Node.js 18+
- PostgreSQL 14+
- Redis 6+

## Setup Steps
1. Clone repository
2. Install dependencies: `npm install`
3. Copy `.env.example` to `.env`
4. Run database migrations: `npm run db:migrate`
5. Start dev server: `npm run dev`

## Common Issues
- **Port conflict**: See Task #189 for resolution
- **Database connection**: Check VPN if remote

Last updated: Dec 2024

Search Across Everything

NoteVault search includes:

• Document titles and content
• Task descriptions and comments
• File names and attachments
• Labels and tags

Search: "oauth implementation"

Results:
├── NoteVault: ADR-002: Auth Strategy
├── NoteVault: API Design > Authentication
├── Task #234: Implement OAuth login
└── Task #235: Add session management

Best Practices for Integrated Documentation

1. Document decisions near tasks — Link ADRs to related work
2. Update docs with code — Part of the PR checklist
3. Use consistent structure — Templates for common doc types
4. Link liberally — Connect docs to tasks to code
5. Archive, don't delete — Keep history accessible
6. Assign doc ownership — Someone responsible for freshness

Migration from Other Tools

From Confluence/Notion

1. Export as Markdown (or HTML → Markdown)
2. Create matching folder structure in NoteVault
3. Import documents
4. Add task links
5. Update internal links

From Google Docs

1. Download as .docx or copy content
2. Paste into NoteVault (auto-converts formatting)
3. Organize in project folders
4. Link to relevant tasks

Related Solutions

• Developer knowledge base
• Technical documentation management
• Project documentation workflow