Pular para o conteúdo principal

ADR-005: Migração da Documentação do Google Drive para Repositório Docusaurus no GitHub

Título

Centralização e migração da documentação técnica do projeto, atualmente dispersa no Google Drive, para um repositório dedicado no GitHub, publicada como wiki estática via Docusaurus.

Status

Aceito

Data

2026-06-17

Contexto​

Desde o início do projeto, a documentação técnica (Especificação de Requisitos, Diário de Decisões Técnicas e demais artefatos) vem sendo mantida no Google Drive de forma paralela ao código-fonte hospedado no GitHub. Essa duplicidade criou os seguintes problemas:

  • Fragmentação: Decisões técnicas e requisitos vivem em um ambiente (Google Drive) enquanto o código e as issues vivem em outro (GitHub), dificultando a navegação e o contexto para novos colaboradores.
  • Rastreabilidade limitada: O Google Drive não oferece versionamento por commit, dificultando entender quando e por que um documento foi alterado.
  • Ausência de revisão estruturada: Alterações em documentos no Drive não passam por Pull Request, impossibilitando revisão antes da publicação.
  • Acesso descentralizado: A documentação exige autenticação no Google e convites manuais, enquanto o repositório GitHub já possui controle de acesso configurado via RBAC (ADR-003).

Decisão​

A equipe decidiu migrar toda a documentação técnica para um repositório dedicado no GitHub, convertendo os documentos para o formato Markdown e publicando-os como uma wiki estática via Docusaurus.

A estrutura adotada será:

  • Um repositório exclusivo para documentação (ex: cruzeiro-remo-docs) dentro da Organização GitHub do projeto.
  • Documentos organizados em Markdown, seguindo as convenções do Docusaurus (pastas docs/, arquivos sidebars.js e docusaurus.config.js).
  • ADRs armazenadas em docs/adr/, nomeadas sequencialmente (ADR-001-*.md, ADR-002-*.md, ...).
  • A wiki será publicada automaticamente via Vercel ou GitHub Pages a cada push na branch principal.
  • O Google Drive deixará de ser o ambiente oficial de documentação; os arquivos existentes serão arquivados e não mais atualizados.

Consequências​

Positivas:

  • Centralização: Toda a documentação, código e decisões técnicas passam a residir no mesmo ecossistema (GitHub), reduzindo o atrito de navegação e onboarding.
  • Versionamento real: Cada alteração em um documento gera um commit rastreável, com autor, data e justificativa.
  • Revisão colaborativa: Mudanças na documentação podem ser propostas via Pull Request e revisadas antes de serem publicadas.
  • Consistência com ADR-003: O controle de acesso à documentação segue o mesmo modelo RBAC já adotado para o código.
  • Wiki navegável: O Docusaurus gera automaticamente uma interface de busca e navegação lateral, tornando a documentação muito mais acessível do que PDFs no Drive.
  • Eliminação de duplicidade: Um único ambiente de verdade para a documentação, reduzindo risco de versões conflitantes.

Negativas:

  • Esforço de migração: Todos os documentos existentes precisam ser convertidos para Markdown e revisados antes de serem publicados.
  • Curva de aprendizado: Colaboradores precisarão se familiarizar com o fluxo de editar documentação via Git/Pull Request em vez de editar diretamente no Google Docs.

Conformidade​

  • Nenhum novo documento técnico oficial deve ser criado no Google Drive após a data desta ADR.
  • Toda nova ADR deve seguir o formato padronizado (este documento) e ser adicionada via Pull Request ao repositório de documentação.
  • O repositório de documentação deve ter proteção de branch ativa na branch principal, exigindo ao menos uma aprovação por PR.
  • O Google Drive deve ser mantido apenas como arquivo histórico, com uma nota indicando que a documentação oficial foi migrada.
  • A URL pública da wiki deve ser referenciada no README.md do repositório principal do projeto.

Observações​

  • Autores: Antonio G. Castro, João Pedro Santos de Brito
  • Versão: 1.0
  • Changelog:
    • 1.0 - 17/06/2026: versão inicial

Referências: