Skip to content

ADR-004: Interfaces de Edição para Portal de Documentação FinOps

Status: Decisão Tomada Data: 19 de fevereiro de 2026
Contexto: Interfaces de edição para usuários não-técnicos
Decisores: Equipe FinOps

1. Contexto e Problema

O portal de documentação FinOps enfrenta barreiras significativas para contribuição de usuários não-técnicos. A atual dependência de conhecimento em Git, Markdown e processos de pull request cria obstáculos que limitam a participação da comunidade. Há necessidade urgente de implementar interfaces de edição mais acessíveis que permitam contribuições diretas, especialmente para usuários de negócio e analistas que precisam documentar processos e conhecimentos específicos.

Problemas identificados:

  • Barreiras Técnicas: Usuários não familiarizados com Git/Markdown
  • Curva de Aprendizado: Processo complexo de contribuição
  • Limitação de Colaboradores: Predominância de contribuições técnicas
  • Perda de Conhecimento: Dificuldade em capturar conhecimento tácito de negócio

2. Opções em Avaliação

Esta ADR apresenta uma análise preliminar das possíveis soluções para interfaces de edição. Ainda não foi tomada uma decisão final - as opções abaixo estão sendo estudadas e avaliadas pela equipe.

3.1 Integração com Fluxo de Slack + Git Pages (Opção Escolhida)

Documentação: Slack Workflows | GitHub Pages

Integração Slack + GitHub Pages: Através de workflows do Slack, os usuários podem escolher ações de documentação (criar, editar ou deletar) e são redirecionados para o GitHub Pages para execução.

Fluxo Técnico de Edição:

  1. Usuário acessa workflow no Slack (botão)
  2. Seleciona ação desejada: criar, editar ou deletar documento
  3. Slack redireciona para GitHub Pages com parâmetros da ação
  4. GitHub Pages carrega interface simplificada baseada na ação escolhida
  5. Edição/criação acontece na interface web do GitHub Pages
  6. Salvamento envia mudanças para repositório Git via API
  7. Commit automático ou pull request via integração GitHub
  8. Rebuild do MkDocs via webhook ou CI/CD
  9. Exclusão via confirmação no GitHub Pages + remoção do arquivo no repositório

Infraestrutura: Slack Workflows + GitHub Pages + API GitHub + CI/CD

Vantagens:

  • Integração nativa com ferramentas corporativas (Slack já usado pela equipe)
  • Fluxo intuitivo através de interface familiar
  • Controle de permissões via Slack e GitHub
  • Redução de barreiras técnicas com interface web simplificada
  • Rastreabilidade de ações através do histórico do Slack

Desvantagens:

  • Dependência de múltiplos serviços (Slack + GitHub Pages + GitHub API)
  • Configuração inicial complexa dos workflows e permissões
  • Limitações do GitHub Pages para funcionalidades avançadas
  • Curva de aprendizado para configuração e manutenção

Viabilidade: Alta - Alinhamento com ferramentas existentes e facilidade de adoção

3.2 StackEdit.io + Integração GitHub

Documentação: TinaCMS | Docusaurus

Fluxo Técnico de Edição:

  1. Edição inline diretamente na página do portal MkDocs
  2. Interface administrativa integrada para criação/edição de conteúdo
  3. Salvamento armazena no banco de dados ou sistema de arquivos
  4. Build automático do MkDocs via webhook ou integração direta
  5. Publicação imediata ou via processo de aprovação
  6. Exclusão via interface administrativa com confirmação e backup

Infraestrutura: Servidor CMS + Banco de dados + Integração MkDocs

Vantagens:

  • Edição diretamente no portal
  • Controle total da experiência do usuário
  • Integração nativa com permissões e workflow

Desvantagens:

  • Desenvolvimento complexo e custoso
  • Manutenção contínua da infraestrutura
  • Curva de aprendizado para administradores
  • Dependência de tecnologias adicionais

Viabilidade: Baixa - Alto custo de desenvolvimento (3-6 meses)

3.3 Google Docs + Conversão Automática

Documentação: Google Docs API

Fluxo Técnico de Edição:

  1. Edição colaborativa no Google Docs com múltiplos usuários
  2. Export automático para Markdown via Google Docs API
  3. Conversão de formato (DOCX → MD) com possível perda de formatação
  4. Upload do arquivo convertido para repositório Git
  5. Commit automático ou via pull request
  6. Rebuild do MkDocs via CI/CD
  7. Exclusão via Google Docs (arquivo movido para lixeira) + sync manual

Infraestrutura: Google Workspace + Conversor + Git + CI/CD

Vantagens:

  • Interface universal conhecida
  • Colaboração em tempo real
  • Sem necessidade de treinamento específico

Desvantagens:

  • Conversão Markdown imperfeita
  • Perda de formatação avançada
  • Dependência de ecossistema Google
  • Controle limitado de versão

Viabilidade: Baixa - Problemas de conversão e controle

3.4 MkDocs Plugins (Netlify CMS, etc.)

Documentação: MkDocs Plugins | Netlify CMS

Fluxo Técnico de Edição:

  1. Interface integrada no próprio MkDocs via plugin
  2. Edição WYSIWYG ou Markdown direto no admin panel
  3. Salvamento diretamente nos arquivos do repositório
  4. Commit automático via integração Git
  5. Build imediato do MkDocs (hot reload)
  6. Exclusão via interface com confirmação e versionamento Git

Infraestrutura: Plugin MkDocs + Integração Git + Servidor local/remoto

Vantagens:

  • Integração nativa com MkDocs
  • Controle total do processo de build
  • Manutenção simplificada

Desvantagens:

  • Funcionalidades limitadas
  • Interface menos intuitiva
  • Suporte limitado a colaboração

Viabilidade: Média - Boa para cenários específicos

4. Análise de Viabilidade e Estudo

4.1 Critérios de Avaliação

  1. Facilidade de Uso: Capacidade de usuários não-técnicos contribuírem
  2. Tempo de Implementação: Velocidade para colocar em produção
  3. Custo Total: Desenvolvimento + manutenção
  4. Escalabilidade: Suporte a crescimento de colaboradores
  5. Confiabilidade: Estabilidade e disponibilidade

4.2 Conclusão do Estudo

Após análise detalhada das opções disponíveis, a Integração com Fluxo de Slack + Git Pages foi selecionada como a solução ideal para o portal de documentação FinOps. Esta opção oferece o melhor equilíbrio entre facilidade de uso, integração com ferramentas corporativas existentes e viabilidade técnica, permitindo uma adoção rápida e eficaz por usuários não-técnicos.

5. Plano de Implementação

Sprint Único (3 semanas)

Semana 1: Configuração e Desenvolvimento Básico

  • Configuração Slack Workflows: Criar workflow para ações de documentação, configurar permissões
  • Desenvolvimento GitHub Pages: Implementar interface web simplificada para edição/criação/deleção
  • Integração Inicial: Conectar Slack com GitHub Pages, testar redirecionamento básico
  • Interface GitHub Pages: Desenvolver formulários e editores para diferentes ações

Semana 2: Integração e Funcionalidades Core

  • API GitHub Integration: Implementar commits automáticos e pull requests via API
  • Integração com MkDocs: Configurar webhook de rebuild, estrutura de pastas, validação de conteúdo
  • Recursos Avançados: Sistema de revisão, notificações, histórico de versões
  • Testes de Usabilidade: Validação com usuários não-técnicos, feedback inicial

Semana 3: Finalização e Monitoramento

  • Documentação e Treinamento: Criar guias de uso, treinamentos para equipe
  • Monitoramento Inicial: Implementar métricas básicas de uso e contribuição
  • Plano de Contingência: Definir alternativas, migração, backup
  • Monitoramento Contínuo: Acompanhamento de métricas, ajustes finais

6. Implementação Técnica Detalhada - Slack + Git Pages

6.1 Configuração Inicial

  1. Conta Slack: Verificar permissões de administrador no workspace corporativo
  2. GitHub Pages: Configurar repositório para servir páginas estáticas
  3. API GitHub: Gerar token de acesso com permissões de escrita no repositório

6.2 Configuração do Slack Workflow

  1. Criar Workflow Builder: Acessar Workflow Builder no Slack
  2. Definir Gatilhos: Criar botões ou comandos para "Criar Documento", "Editar Documento", "Deletar Documento"
  3. Configurar Ações: Adicionar steps para coletar informações (título, tipo de documento, etc.)
  4. Redirecionamento: Configurar webhook para redirecionar usuário para GitHub Pages com parâmetros

6.3 Desenvolvimento da Interface GitHub Pages

  1. Estrutura HTML/CSS/JS: Criar interface web responsiva hospedada no GitHub Pages
  2. Formulários Dinâmicos: Desenvolver formulários baseados na ação selecionada no Slack
  3. Criar: Formulário com campos para título, categoria, conteúdo inicial
  4. Editar: Lista de documentos existentes + editor Markdown

  5. Deletar: Lista de documentos com confirmação de exclusão

  6. Integração GitHub API: Implementar funções JavaScript para:

  7. Buscar lista de arquivos do repositório
  8. Criar/editar/deletar arquivos via API
  9. Criar commits ou pull requests automaticamente

6.4 Integração com MkDocs

  1. Webhook de Rebuild: Configurar webhook no GitHub para acionar rebuild automático
  2. Estrutura de Pastas: Manter organização de arquivos compatível com MkDocs
  3. Validação de Conteúdo: Implementar checagem básica de sintaxe Markdown antes do commit

6.3 Funcionalidades Avançadas

  1. Modo Offline: Suporte a edição sem conexão
  2. Sincronização Automática: Salvamento automático no GitHub
  3. Preview em Tempo Real: Visualização da renderização Markdown
  4. Histórico de Versões: Controle de versão integrado

6.4 Validação e Qualidade

  1. Linting Markdown: Verificação automática de sintaxe
  2. Validação de Links: Checagem de links quebrados
  3. Controle de Permissões: Restrição de edição por usuário/grupo

6.5 Testes e Validação

  1. Testes de Usabilidade: Sessões com usuários não-técnicos
  2. Testes de Performance: Medição de tempo de carregamento
  3. Testes de Integração: Validação do fluxo completo GitHub → MkDocs

7. Referências

Última Atualização: 19 de fevereiro de 2026
Versão: 1.0
Autores: Carolina Bratos
Revisores: Gabriel Pepe, Eduardo Alcebiades e Adriano Valerio