La Documentación Vive Separada de Tareas y Código

Cuando la documentación vive en herramientas separadas de las tareas y el código, los equipos pierden tiempo buscando, el contexto se pierde y el conocimiento se vuelve obsoleto. NoteVault de GitScrum integra la documentación directamente con proyectos y tareas.

El Problema de Fragmentación de Documentación

La documentación dispersa crea fricción diaria:

• Fatiga de búsqueda — Buscar en múltiples lugares por respuestas
• Información obsoleta — Docs no actualizados cuando el código cambia
• Pérdida de contexto — Sin enlace entre docs y tareas relacionadas
• Fricción de onboarding — Nuevos desarrolladores no encuentran información
• Contenido duplicado — Misma info escrita en múltiples lugares

Dispersión Común de Documentación

GitScrum NoteVault: Documentación Unificada

NoteVault trae la documentación a tu workspace de proyecto:

Características

• Editor Markdown — Formato rico sin complejidad
• Organización por carpetas — Estructura jerárquica por proyecto
• Búsqueda full-text — Encuentra cualquier cosa en todos los docs
• Enlace a tareas — Conecta docs a tareas relacionadas
• Historial de versiones — Rastrea cambios en el tiempo
• Edición colaborativa — El equipo puede actualizar junto

Estructura de Documentación

Organiza docs dentro de tu proyecto:

Proyecto: Rediseño Dashboard
└── NoteVault/
    ├── Arquitectura/
    │   ├── Vista General del Sistema
    │   ├── Diseño de API
    │   └── Esquema de Base de Datos
    ├── Guías/
    │   ├── Setup de Desarrollo
    │   ├── Proceso de Deploy
    │   └── Estrategia de Testing
    ├── Decisiones/
    │   ├── ADR-001: Elección de Framework
    │   ├── ADR-002: Estrategia de Auth
    │   └── ADR-003: Gestión de Estado
    └── Referencias/
        ├── Endpoints de API
        ├── Variables de Entorno
        └── Servicios de Terceros

Enlazando Documentación a Tareas

De Tarea a Documentación

Al crear o ver una tarea, enlaza a docs relevantes:

Tarea: Implementar login OAuth
├── Descripción: Agregar soporte OAuth de Google
├── Docs Enlazados:
│   ├── ADR-002: Estrategia de Auth
│   ├── Diseño de API > Autenticación
│   └── Setup de Desarrollo > Config OAuth
└── Comentarios: Ver docs enlazados para detalles de implementación

De Documentación a Tareas

Referencia tareas dentro de la documentación:

## Implementación de Autenticación

Para detalles de implementación, ver:
- [Tarea #234: Implementar login OAuth](/proyecto/tareas/234)
- [Tarea #235: Agregar gestión de sesión](/proyecto/tareas/235)

Estado: En Progreso (Sprint 14)

Workflows de Documentación

Registros de Decisión de Arquitectura (ADRs)

Documenta decisiones donde son accionables:

# ADR-002: Estrategia de Autenticación

## Estado
Aceptado

## Contexto
Necesitamos implementar autenticación de usuario para el dashboard.

## Decisión
Usar OAuth 2.0 con Google como proveedor principal.

## Consecuencias
- Implementación más simple (sin gestión de contraseñas)
- Dependencia de disponibilidad de Google
- SSO empresarial puede agregarse después

## Tareas Relacionadas
- #234: Implementar login OAuth
- #235: Agregar gestión de sesión
- #236: Crear flujo de logout

Especificaciones Técnicas

Mantén specs cerca de la implementación:

# Especificación API: Endpoints de Usuario

## GET /api/users/:id

Retorna datos de perfil de usuario.

### Respuesta
| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | string | Identificador único de usuario |
| email | string | Dirección de email del usuario |
| name | string | Nombre para mostrar |

### Implementación
- Tarea: #247
- Sprint: 14
- Estado: Completo

Guías de Onboarding

Documentación viva que evoluciona con el proyecto:

# Onboarding de Desarrollador

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

## Pasos de Setup
1. Clonar repositorio
2. Instalar dependencias: `npm install`
3. Copiar `.env.example` a `.env`
4. Ejecutar migraciones de DB: `npm run db:migrate`
5. Iniciar servidor dev: `npm run dev`

## Problemas Comunes
- **Conflicto de puerto**: Ver Tarea #189 para resolución
- **Conexión de DB**: Verificar VPN si es remoto

Última actualización: Dic 2024

Buscar en Todo

La búsqueda de NoteVault incluye:

• Títulos y contenido de documentos
• Descripciones y comentarios de tareas
• Nombres de archivos y adjuntos
• Labels y tags

Búsqueda: "implementación oauth"

Resultados:
├── NoteVault: ADR-002: Estrategia de Auth
├── NoteVault: Diseño de API > Autenticación
├── Tarea #234: Implementar login OAuth
└── Tarea #235: Agregar gestión de sesión

Mejores Prácticas para Documentación Integrada

1. Documenta decisiones cerca de tareas — Enlaza ADRs a trabajo relacionado
2. Actualiza docs con código — Parte del checklist de PR
3. Usa estructura consistente — Templates para tipos comunes de doc
4. Enlaza liberalmente — Conecta docs a tareas a código
5. Archiva, no borres — Mantén historial accesible
6. Asigna propiedad de docs — Alguien responsable de frescura

Migración desde Otras Herramientas

Desde Confluence/Notion

1. Exportar como Markdown (o HTML → Markdown)
2. Crear estructura de carpetas coincidente en NoteVault
3. Importar documentos
4. Agregar enlaces a tareas
5. Actualizar enlaces internos

Desde Google Docs

1. Descargar como .docx o copiar contenido
2. Pegar en NoteVault (auto-convierte formato)
3. Organizar en carpetas de proyecto
4. Enlazar a tareas relevantes

Soluciones Relacionadas

• Base de conocimiento para desarrolladores
• Gestión de documentación técnica
• Workflow de documentación de proyectos