Criar documentação de API em Excel ou PDF e compartilhá-la por e-mail é algo familiar demais.
Quando surge um problema, entra-se em contato com a pessoa responsável e procura-se em e-mails antigos para verificar qual versão do documento o cliente tem. Explicam-se novamente as mudanças, envia-se o documento corrigido e depois ainda é preciso confirmar se tudo foi refletido corretamente.
Repetimos esse processo tantas vezes que passamos a considerá-lo parte natural do trabalho.
Mas o problema não termina em um único documento errado.
Sempre que a API muda, acumulam-se novos arquivos e e-mails, exceções por cliente e lembranças dos responsáveis. No começo é um pequeno incômodo, mas com o tempo fica cada vez mais difícil saber qual documento é a referência, e também aumentam as pessoas e o tempo necessários para resolver os problemas.
Se o cliente desenvolver com base no formato de requisição de uma versão anterior, surgem erros de integração e retrabalho. Se campos obrigatórios ou o método de autenticação forem repassados de forma diferente, o cronograma de desenvolvimento atrasa e, se for uma API já em produção, isso pode até levar a erros de dados ou indisponibilidades.
Só depois que o problema acontece é que se descobre que a equipe interna de desenvolvimento e o cliente estavam olhando documentos diferentes.
A partir daí, o desenvolvedor para o que estava fazendo para identificar a causa. A equipe de operações procura documentos antigos e o histórico de envio, e o cliente volta a validar a própria implementação e a especificação recebida. Uma única divergência documental pode interromper ao mesmo tempo o trabalho de várias pessoas.
Mesmo assim, a maioria dos problemas é resolvida discretamente por telefone, e-mail e mensageiros.
Alguém reenviará o arquivo corrigido, alguém explicará a situação ao cliente, e o desenvolvedor adicionará um tratamento de exceção às pressas. O problema imediato é resolvido, mas a organização não registra por que ele aconteceu, quais clientes foram afetados nem o que foi mudado para evitar que o mesmo erro se repita.
O tempo gasto nesse processo é tempo que deveria ter sido usado em desenvolvimento e melhoria do produto.
O problema maior é que todo esse processo depende da experiência, da memória e da caixa de e-mail de uma pessoa específica. Se essa pessoa se ausenta ou sai da empresa, a organização precisa vasculhar e-mails e registros de mensageiros para reconstruir o trabalho.
Documentação de API sem gestão não desaparece. Ela continua existindo dentro e fora da organização e se transforma em uma dívida documental invisível.
Talvez não estejamos realmente resolvendo o problema, mas apenas acostumados a bloqueá-lo com tempo humano sempre que ele aparece.
Depois de enfrentar esse problema no trabalho real, criei o SpecBridge.
O SpecBridge não é apenas uma ferramenta para escrever documentação de API. É uma ferramenta de operação de documentação de API que revisa alterações e distribui aos clientes e parceiros externos apenas as versões aprovadas.
Em vez de substituir o Swagger, o foco foi importar Swagger/OpenAPI e Postman Collection e gerenciar os problemas que surgem no processo de compartilhamento externo.
- Comparação entre a versão atualmente publicada e a versão modificada
- Revisão e aprovação de mudanças
- Separação entre rascunhos e a versão publicada que o cliente vê
- Gestão do escopo de visibilidade da documentação por cliente
- Definição de senha e data de expiração para links públicos
- Entrega da versão mais recente aprovada no mesmo link
Sem precisar enviar um novo arquivo ao cliente toda vez, é possível republicar no link existente apenas os documentos que concluíram a revisão interna.
Os desenvolvedores reduzem o trabalho repetitivo de procurar e reenviar documentos, e a organização pode gerenciar a documentação de API não com base na memória de uma pessoa específica, mas no histórico registrado de mudanças e nos critérios de publicação.
No momento, estou procurando parceiros que usem o SpecBridge na operação real de documentação de API e possam dar feedback sincero.
Se sua equipe gerencia documentação de API em Excel ou PDF, ou reenviam documentação ao cliente sempre que a API muda, gostaria de validar junto com vocês a partir de um documento que já esteja em uso hoje.
Mais do que elogios a funcionalidades bem feitas, quero ouvir opiniões honestas sobre pontos incômodos na operação real, procedimentos desnecessários e recursos que ainda faltam.
Ainda não há comentários.