001-stack-documentacao¶

Metadado	Valor
Status	Aceito
Data	06-01-2026
Decisores	JGustavoCN
Contexto	Engenharia & Gestão de Conhecimento

Resumo Executivo

Adoção do MkDocs (Material Theme) como plataforma de documentação. A escolha prioriza a velocidade de migração de 550 páginas de legado e a facilidade de manutenção (Markdown puro), superando a flexibilidade do Docusaurus e a performance de build do Hugo.

1. Contexto e Problema¶

O projeto DataProfiler iniciou com um passivo de conhecimento bruto de aproximadamente 550 páginas (anotações, regras de negócio e estudos).

A ausência de uma plataforma centralizada gerou riscos críticos:

Fragmentação: Informações dispersas dificultam a consulta ("Onde está a regra de Regex?").
Obsolescência: Documentos fora do repositório (Google Docs/Word) não acompanham a evolução do código Go.
Manutenibilidade: A falta de estrutura hierárquica torna o onboarding inviável.

2. Drivers da Decisão (Requisitos)¶

Docs as Code: A documentação deve ser versionada no Git junto ao código-fonte.
Foco no Conteúdo: A ferramenta deve exigir esforço zero de design/CSS para escrever novas páginas.
Suporte a Diagramas: Renderização nativa de Mermaid.js (evitando imagens estáticas).
Busca e Navegação: Indexação robusta para grande volume de dados.

3. Opções Consideradas¶

Opção A: Docusaurus (React)¶

Gerador de sites estáticos baseado em React/Node.js.

Prós

Stack Unificada: Mesma tecnologia do Frontend do projeto.
Componentização: Permite embutir componentes React interativos na doc.

Contras

Complexidade Acidental: Exige tratar a doc como uma aplicação React completa.
Overkill: Flexibilidade desnecessária para o objetivo atual (apenas texto/regras).

Opção B: Hugo (Go)¶

Gerador de sites estáticos escrito em Go, famoso pela velocidade de compilação.

Prós

Alinhamento de Backend: Escrito na mesma linguagem do Core do projeto (Go).
Performance: Build extremamente rápido (<1ms/página), ideal para milhares de páginas.
Single Binary: Instalação simples, sem dependências de runtime (como Node ou Python).

Contras

Curva de Aprendizado: O sistema de templates do Go ({{ range .Params }}) é complexo para customizações simples.
Falta de Temas Prontos: Não possui um tema de documentação "out-of-the-box" tão rico em features quanto o Material for MkDocs.

Opção C: MkDocs + Material (Python) - ESCOLHIDA¶

Gerador focado exclusivamente em documentação técnica, configurado via YAML.

Prós

Simplicidade: Configuração declarativa (mkdocs.yml). Zero código para iniciar.
UX de Ponta: O tema Material já entrega busca, dark mode, admonitions e abas prontos.
Diagramas: Suporte a Mermaid via plugin superfences é o mais maduro do mercado.

Contras

Dependência: Introduz Python no ecossistema (mitigado via Makefile).

4. Decisão¶

Foi selecionada a Opção C (MkDocs + Material).

Justificativa Técnica¶

Embora o Hugo (Opção B) fosse a escolha natural pela linguagem (Go), o ecossistema de temas do MkDocs (especificamente o Material Theme) oferece funcionalidades de UX superiores sem necessidade de desenvolvimento customizado.

Dada a urgência em organizar 550 páginas, o MkDocs vence pela relação "Esforço vs. Resultado". O Docusaurus (Opção A) foi descartado por adicionar complexidade de manutenção desnecessária neste estágio.


graph TD
    A["Requisito: Organizar 550 Páginas"] --> B{"Escolha da Ferramenta"}
    B -->|"Docusaurus"| C["Alta Manutenção (React)"]
    B -->|"Hugo"| D["Alta Performance / Baixa UX Padrão"]
    B -->|"MkDocs"| E["Alta Produtividade / UX Pronta"]
    E --> F["Decisão Final"]

5. Consequências¶

Tipo	Descrição
Positivo	Equipe foca 100% na escrita de regras, não em layout.
Positivo	Padronização visual imediata (Look & Feel Enterprise).
Risco	Dependência de ambiente Python em um projeto Go (Mitigação: Uso de Docker/Makefile).