Documentação Vive Separada de Tarefas e Código

Quando a documentação vive em ferramentas separadas das tarefas e código, equipes perdem tempo buscando, contexto se perde e conhecimento fica obsoleto. NoteVault do GitScrum integra documentação diretamente com projetos e tarefas.

O Problema da Fragmentação de Documentação

Documentação dispersa cria fricção diária:

• Fadiga de busca — Procurar em múltiplos lugares por respostas
• Informação obsoleta — Docs não atualizados quando código muda
• Perda de contexto — Sem link entre docs e tarefas relacionadas
• Fricção de onboarding — Novos desenvolvedores não encontram informação
• Conteúdo duplicado — Mesma info escrita em múltiplos lugares

Dispersão Comum de Documentação

GitScrum NoteVault: Documentação Unificada

NoteVault traz documentação para seu workspace de projeto:

Recursos

• Editor Markdown — Formatação rica sem complexidade
• Organização por pastas — Estrutura hierárquica por projeto
• Busca full-text — Encontre qualquer coisa em todos os docs
• Vínculo a tarefas — Conecte docs a tarefas relacionadas
• Histórico de versões — Rastreie mudanças ao longo do tempo
• Edição colaborativa — Equipe pode atualizar junto

Estrutura de Documentação

Organize docs dentro do seu projeto:

Projeto: Redesign Dashboard
└── NoteVault/
    ├── Arquitetura/
    │   ├── Visão Geral do Sistema
    │   ├── Design de API
    │   └── Schema de Banco de Dados
    ├── Guias/
    │   ├── Setup de Desenvolvimento
    │   ├── Processo de Deploy
    │   └── Estratégia de Testes
    ├── Decisões/
    │   ├── ADR-001: Escolha de Framework
    │   ├── ADR-002: Estratégia de Auth
    │   └── ADR-003: Gerenciamento de Estado
    └── Referências/
        ├── Endpoints de API
        ├── Variáveis de Ambiente
        └── Serviços de Terceiros

Vinculando Documentação a Tarefas

De Tarefa para Documentação

Ao criar ou visualizar uma tarefa, vincule a docs relevantes:

Tarefa: Implementar login OAuth
├── Descrição: Adicionar suporte OAuth do Google
├── Docs Vinculados:
│   ├── ADR-002: Estratégia de Auth
│   ├── Design de API > Autenticação
│   └── Setup de Desenvolvimento > Config OAuth
└── Comentários: Veja docs vinculados para detalhes de implementação

De Documentação para Tarefas

Referencie tarefas dentro da documentação:

## Implementação de Autenticação

Para detalhes de implementação, veja:
- [Tarefa #234: Implementar login OAuth](/projeto/tarefas/234)
- [Tarefa #235: Adicionar gestão de sessão](/projeto/tarefas/235)

Status: Em Progresso (Sprint 14)

Workflows de Documentação

Registros de Decisão de Arquitetura (ADRs)

Documente decisões onde são acionáveis:

# ADR-002: Estratégia de Autenticação

## Status
Aceito

## Contexto
Precisamos implementar autenticação de usuário para o dashboard.

## Decisão
Usar OAuth 2.0 com Google como provedor principal.

## Consequências
- Implementação mais simples (sem gestão de senhas)
- Dependência da disponibilidade do Google
- SSO empresarial pode ser adicionado depois

## Tarefas Relacionadas
- #234: Implementar login OAuth
- #235: Adicionar gestão de sessão
- #236: Criar fluxo de logout

Especificações Técnicas

Mantenha specs perto da implementação:

# Especificação API: Endpoints de Usuário

## GET /api/users/:id

Retorna dados de perfil do usuário.

### Resposta
| Campo | Tipo | Descrição |
|-------|------|-----------|
| id | string | Identificador único do usuário |
| email | string | Endereço de email do usuário |
| name | string | Nome de exibição |

### Implementação
- Tarefa: #247
- Sprint: 14
- Status: Completo

Guias de Onboarding

Documentação viva que evolui com o projeto:

# Onboarding de Desenvolvedor

## Pré-requisitos
- Node.js 18+
- PostgreSQL 14+
- Redis 6+

## Passos de Setup
1. Clonar repositório
2. Instalar dependências: `npm install`
3. Copiar `.env.example` para `.env`
4. Executar migrações de DB: `npm run db:migrate`
5. Iniciar servidor dev: `npm run dev`

## Problemas Comuns
- **Conflito de porta**: Veja Tarefa #189 para resolução
- **Conexão de DB**: Verifique VPN se remoto

Última atualização: Dez 2024

Buscar em Tudo

A busca do NoteVault inclui:

• Títulos e conteúdo de documentos
• Descrições e comentários de tarefas
• Nomes de arquivos e anexos
• Labels e tags

Busca: "implementação oauth"

Resultados:
├── NoteVault: ADR-002: Estratégia de Auth
├── NoteVault: Design de API > Autenticação
├── Tarefa #234: Implementar login OAuth
└── Tarefa #235: Adicionar gestão de sessão

Melhores Práticas para Documentação Integrada

1. Documente decisões perto de tarefas — Vincule ADRs a trabalho relacionado
2. Atualize docs com código — Parte do checklist de PR
3. Use estrutura consistente — Templates para tipos comuns de doc
4. Vincule liberalmente — Conecte docs a tarefas a código
5. Arquive, não delete — Mantenha histórico acessível
6. Atribua propriedade de docs — Alguém responsável pela atualidade

Migração de Outras Ferramentas

Do Confluence/Notion

1. Exportar como Markdown (ou HTML → Markdown)
2. Criar estrutura de pastas correspondente no NoteVault
3. Importar documentos
4. Adicionar links para tarefas
5. Atualizar links internos

Do Google Docs

1. Baixar como .docx ou copiar conteúdo
2. Colar no NoteVault (auto-converte formatação)
3. Organizar em pastas de projeto
4. Vincular a tarefas relevantes

Soluções Relacionadas

• Base de conhecimento para desenvolvedores
• Gestão de documentação técnica
• Workflow de documentação de projetos