Migrar documentação para nova estrutura

[camilamaia]

Descrição

Realizar a migração da documentação atual para a nova estrutura definida.

Atualmente temos:

• docs-temp: documentação atual em .md soltos (estrutura antiga, sem MkDocs)
• docs: nova estrutura organizada (com MkDocs)

O objetivo é migrar todo o conteúdo relevante da docs-temp para a docs, adaptando ao novo formato e consolidando a nova documentação como fonte principal.

---

Contexto

A documentação atual está em arquivos Markdown soltos, sem uma estrutura padronizada, o que dificulta:

• navegação
• manutenção
• onboarding
• escalabilidade

A nova estrutura (docs) resolve esses pontos, mas ainda precisa ser populada com o conteúdo existente.

---

Escopo

A migração deve contemplar:

1. Preparação

• Revisar a estrutura da docs (MkDocs)
• Garantir que a navegação (nav) está definida ou preparada
• Definir critérios do que deve ou não ser migrado

---

2. Mapeamento de conteúdo

• Mapear todos os arquivos da docs-temp

• Definir onde cada conteúdo se encaixa na nova estrutura (docs)

• Identificar conteúdos que:

  • devem ser migrados
  • devem ser adaptados
  • podem ser removidos ou arquivados

---

3. Migração e adaptação

• Migrar conteúdos da docs-temp para a docs
• Adaptar os arquivos para o padrão do MkDocs (estrutura, navegação, organização em pastas)
• Reescrever ou ajustar conteúdos quando necessário
• Garantir consistência entre páginas

---

4. Revisão

• Revisar conteúdo migrado
• Validar clareza, organização e navegabilidade
• Garantir que não há duplicações ou conteúdos desatualizados

---

5. Comunicação pré-migração

Antes da consolidação:

• Avisar a comunidade sobre a mudança

• Explicar:

  • o que está mudando (nova estrutura com MkDocs)
  • por que está mudando
  • o que esperar durante a transição

---

6. Consolidação

• Definir a docs como fonte oficial de documentação
• Atualizar links em repositórios, READMEs e outros pontos de entrada
• Arquivar ou remover a docs-temp (ou manter como histórico, se fizer sentido)

---

7. Comunicação pós-migração

Após a migração:

• Avisar que a nova documentação está no ar

• Explicar como ela está organizada

• Apontar:

  • onde encontrar conteúdos
  • como contribuir
  • como criar novas páginas (ex: núcleos, guias, etc)

---

8. Pós-migração (melhoria contínua)

• Coletar feedback da comunidade
• Ajustar estrutura e conteúdos com base no uso real
• Corrigir gaps e melhorar a documentação iterativamente

---

Critérios de aceitação

• Todo conteúdo relevante da docs-temp foi migrado, adaptado ou arquivado
• A docs está organizada e navegável via MkDocs
• Links principais foram atualizados
• A comunidade foi comunicada antes e depois da mudança
• Está claro como navegar e contribuir na nova documentação

Sugestão (opcional)

Criar tarefas menores como sub-issues para facilitar gerenciamento. Por exemplo:

• Mapear arquivos da docs-temp
• Definir estrutura final no MkDocs (nav)
• Migrar conteúdos prioritários
• Adaptar conteúdos para o novo formato
• Revisar documentação
• Comunicar pré-migração
• Consolidar docs como oficial
• Comunicar pós-migração
• Arquivar docs-temp
• Coletar feedback