Dívida de Documentação: Por que os diagramas ficam obsoletos e como evitá-la

Dívida de Documentação: Por que os diagramas ficam obsoletos e como evitá-la

O diagrama de arquitetura na página do SharePoint foi criado em 2009. Era preciso na época, refletindo o sistema como existia durante uma grande migração de plataforma, desenhado por um arquiteto que passou três semanas documentando cada componente e seus relacionamentos. Desde 2009, o sistema recebeu aproximadamente 4,800 commits, quinze equipes contribuíram para ele, quatro dos componentes mostrados no diagrama não existem mais, onze novos componentes foram adicionados e nunca foram diagramados, e o arquiteto que o desenhou se aposentou em 2016. O diagrama ainda existe. Quando um novo desenvolvedor entra na equipe e pergunta "como o sistema funciona?", alguém lhe envia o link do SharePoint. O diagrama não é documentação. É arqueologia.

A dívida de documentação é a dívida técnica aplicada à camada de documentação: a lacuna acumulada entre o que a documentação diz sobre um sistema e o que o sistema realmente faz. A deriva arquitetural, onde os diagramas se desconectam dos sistemas que representam, é a forma mais comum e mais perigosa de dívida de documentação. É a mais perigosa porque cria uma falsa sensação de segurança: um diagrama existente e com aparência profissional dá aos stakeholders a impressão de que o sistema é compreendido, quando na verdade o que eles estão vendo é um artefato histórico que descreve um sistema que não existe mais na forma apresentada. Diagramas desatualizados são piores do que a ausência de diagramas, porque a falta deles leva as pessoas a descobrir o que realmente existe; diagramas desatualizados levam as pessoas a agir com base em algo que não é mais verdade.

Documentação sem esforço

SMART TS XL Gera um registro de alterações de cada programa, dependência e modificação de copybook desde a última execução da análise.

SAIBA MAIS…

Os cinco mecanismos que fazem os diagramas ficarem obsoletos.

Todos os artigos sobre a deriva de documentação afirmam que "os diagramas ficam obsoletos com o tempo". Quase nenhum explica os mecanismos específicos pelos quais isso acontece. Compreender esses mecanismos é fundamental para preveni-los, pois mecanismos diferentes exigem estratégias de prevenção diferentes.

1. O problema do acúmulo de alterações. Um diagrama é um instantâneo de um sistema em um determinado momento. Cada alteração de código após esse instantâneo representa uma diferença entre o diagrama e a realidade. As alterações individuais geralmente são pequenas: um novo serviço, um componente renomeado, uma dependência adicionada. Cada uma é fácil de documentar isoladamente. O problema é que ninguém as documenta incrementalmente, porque atualizar o diagrama para cada alteração é percebido como um custo adicional sem benefício imediato. Após 100 alterações não registradas, o diagrama está materialmente incorreto. Após 1,000, torna-se substancialmente fictício.

2. O problema da proveniência ausente. Um diagrama que não possui vínculo programático com o código que representa não tem mecanismo para detectar quando se torna impreciso. Não há sinal que seja acionado quando uma alteração no código-fonte contradiz uma afirmação no diagrama. O diagrama e o código são artefatos desconectados que por acaso descrevem o mesmo sistema, mas a conexão existe apenas na mente das pessoas que desenharam o diagrama, e apenas enquanto essas pessoas se lembrarem dele.

3. O problema da transferência de responsabilidade. Os diagramas de arquitetura são normalmente criados por uma pessoa específica em um momento específico. Quando essa pessoa sai, o conhecimento tácito que tornava o diagrama preciso, a compreensão de quais componentes foram intencionalmente omitidos, quais relacionamentos foram simplificados, quais rótulos eram abreviações para algo mais complexo, desaparece com ela. O novo responsável pelo diagrama herda um artefato que não criou, que pode não compreender completamente e que não tem incentivo para manter em relação a uma base de código que não projetou.

4. O problema da obsolescência por excesso de precisão. Diagramas que mostram detalhes em excesso tornam-se obsoletos mais rapidamente do que diagramas que mostram abstrações adequadas. Um diagrama que mostra cada microsserviço, cada endpoint de API e cada tabela de banco de dados precisa ser atualizado a cada implantação. Um diagrama que mostra domínios de serviço e seus principais padrões de interação precisa ser atualizado apenas quando os limites dos domínios mudam. Diagramas excessivamente precisos têm uma meia-vida de obsolescência medida em sprints; diagramas com abstração adequada têm uma meia-vida de obsolescência medida em trimestres.

5. O problema da dependência de formato. Diagramas armazenados como arquivos do Visio, slides do PowerPoint, exportações em PNG ou anexos em PDF não podem ser gerados, validados ou comparados programaticamente. Não há como perguntar "este diagrama ainda corresponde ao código?", porque o diagrama é uma imagem pixelada e o código é texto. A escolha do formato feita na criação do diagrama determina se ele poderá ser validado em relação ao sistema que representa.

A Catástrofe da Documentação do Sistema Legado

Para sistemas modernos nativos da nuvem com equipes de desenvolvimento ativas, a desatualização dos diagramas é um problema de gerenciamento, resolvido com práticas de arquitetura como código, ferramentas de documentação viva e disciplina de engenharia. O sistema muda frequentemente; o diagrama pode ser atualizado para acompanhar essas mudanças, desde que o processo seja adequado.

Para sistemas legados, o problema é de natureza diferente, não apenas de grau.

Um diagrama de arquitetura elaborado durante uma revisão de projeto de um sistema mainframe em 1992 pode ter acumulado 30 anos de alterações de código desde sua criação. Cada ano de manutenção ativa em um portfólio COBOL complexo gera centenas de commits, novos programas adicionados, programas antigos desativados, copybooks atualizados e fluxos de jobs JCL reorganizados. O diagrama de 1992 era preciso na época. Desde então, sua precisão tem se tornado progressivamente menor. Em 2026, a discrepância entre o diagrama e o sistema pode ser maior do que o próprio sistema original, havendo mais programas novos que não constam no diagrama do que programas do sistema original que ainda funcionam conforme o projeto original.

O que torna isso catastrófico, e não apenas inconveniente, é a forma como o diagrama é usado. Quando uma equipe de modernização chega para avaliar o sistema, ela não sabe que o diagrama está errado. Não tem como saber o quão errado ele está. O diagrama parece profissional. Tem caixas de componentes, setas de relacionamento, anotações. Sugere que alguém entendeu o sistema bem o suficiente para desenhá-lo. A equipe o usa como ponto de partida, e toda análise construída sobre um ponto de partida errado produz conclusões erradas.

A estrutura de auditoria do Docuwriter é clara: uma auditoria de documentação adequada "transforma uma vaga insegurança em fatos verificáveis". Para sistemas legados, a auditoria de documentação quase sempre produz a mesma conclusão: os diagramas estão ausentes ou são tão antigos que representam um sistema que não existe há anos. Os fatos verificáveis, quando finalmente vêm à tona, descrevem um sistema substancialmente diferente daquele com o qual todos estavam trabalhando.

O modo de falha específico: uma equipe de modernização estimou o escopo da migração a partir do diagrama de 1992. Este mostrava 180 componentes. A análise estrutural da base de código real revelou 340 programas, dos quais 80 eram código morto e outros 40 foram adicionados após 1992 e nunca foram diagramados. A estimativa de escopo estava errada por um fator de dois antes mesmo da primeira linha de código novo ser escrita.

Categorias do diagrama por taxa de obsolescência

Nem todos os diagramas se tornam obsoletos na mesma velocidade. A taxa de obsolescência depende do que o diagrama representa, da frequência com que os elementos representados mudam e da precisão com que o diagrama representa esses elementos.

Tipo de diagramaO que muda frequentementeTaxa de obsolescênciaPrioridade de mitigação
Inventário de serviços/componentesNovos serviços adicionados, serviços antigos desativadosAltoCrítico — frequência de mudança mais alta
Mapa de dependências/integraçãoAPIs adicionadas, integrações alteradas, fluxos de dados modificadosAltoCrítico — cada implementação pode mudar isso.
Modelo de dados / DERAlterações de esquema, novas tabelas, modificações de colunasMédio-altoAlta — mudanças de esquema são frequentes em desenvolvimento ativo.
Diagramas de sequênciaAlterações na lógica de negócios, atualizações de contrato de APISuporte:Alta — qualquer alteração no fluxo de trabalho invalida estas condições.
Infraestrutura/implantaçãoA infraestrutura como código impulsiona mudanças frequentes.AltoMédio — As ferramentas de IaC podem gerar isso automaticamente.
Domínio / contexto delimitadoMudanças organizacionais e de propriedadeMédio baixoBaixa — os limites do domínio mudam trimestralmente ou menos.
Registros de decisão (ADRs)Raramente mudam (as decisões são históricas)Muito baixoBaixo — uma vez registrado corretamente, permanece preciso.
Gráfico de chamada de programa (COBOL)Cada alteração no código pode potencialmente mudar isso.Muito altoFundamental para o legado — mudanças invisíveis
Copybook / esquema (COBOL)Cada alteração de FD afeta vários programas.AltoFundamental para o legado — as mudanças se propagam silenciosamente.

As duas últimas linhas representam as entradas específicas de sistemas legados que não são abordadas por nenhuma documentação padrão. Um gráfico de chamadas de um programa COBOL pode ser invalidado a cada alteração de código em qualquer programa na árvore de chamadas. Um copybook compartilhado por 200 programas é invalidado para todos os programas quando o copybook é alterado. Esses diagramas apresentam a maior taxa de obsolescência em qualquer portfólio corporativo e as consequências mais graves quando se tornam obsoletos, pois os programas que descrevem são os que executam os processos de negócios mais críticos.

A Solução da Proveniência: Rastreando Diagramas até sua Origem

A causa principal da dívida de documentação não é a ausência de um processo de atualização da documentação. É a ausência de proveniência, o vínculo rastreável de um elemento do diagrama ao artefato de código que ele representa. Sem proveniência, não há mecanismo para detectar a obsolescência. Com proveniência, a detecção de obsolescência é automática: se o artefato de código foi alterado desde a geração do diagrama, o diagrama está obsoleto.

A proveniência em documentos existe em dois níveis:

Proveniência estática A documentação é gerada a partir do código em um determinado momento, com um registro de data e hora de geração e uma referência ao estado do código (hash do commit, versão, data da análise) que a documentação reflete. A proveniência estática não impede a obsolescência, mas a torna detectável: o registro de data e hora mostra que a documentação foi gerada a partir do commit abc123 em uma data específica, e o commit atual é def456 em uma data posterior. O intervalo entre os dois commits é o intervalo entre a documentação e o código atual.

A proveniência dinâmica é a documentação gerada continuamente a partir do código, regenerada a cada alteração relevante. A documentação está sempre atualizada porque é sempre derivada do estado atual do código. Este é o modelo de documentação viva, não diagramas que alguém atualiza quando se lembra, mas diagramas que são regenerados a partir do código sempre que este é alterado.

A diferença prática para um portfólio COBOL legado: uma abordagem de proveniência estática gera o diagrama de dependências a partir da análise do código-fonte COBOL atual e o marca com um carimbo de data/hora. Semanalmente, a análise pode ser executada novamente e o novo diagrama comparado ao anterior. As alterações são visíveis como diferenças entre as saídas de análises consecutivas. Uma abordagem de proveniência dinâmica integra a análise ao pipeline de gerenciamento de mudanças do mainframe, gerando um diagrama atualizado sempre que um programa é promovido para produção.

Diagramas como código: o que funciona e o que não funciona

A resposta moderna aos diagramas estáticos obsoletos é o uso de diagramas como código, que expressam a documentação arquitetural em um formato de texto que pode ser versionado, comparado, revisado e gerado programaticamente. Mermaid, PlantUML e o modelo C4 em formato de código são as principais ferramentas.

For modern cloud-native systems, diagrams-as-code solves several of the staleness mechanisms: #mermaid-rlk-r1 { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 .edge-animation-slow { stroke-dashoffset: 900; animation: 50s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .edge-animation-fast { stroke-dashoffset: 900; animation: 20s linear 0s infinite normal none running dash; stroke-linecap: round; stroke-dasharray: 9, 5 !important; } #mermaid-rlk-r1 .error-icon { fill: rgb(204, 120, 92); } #mermaid-rlk-r1 .error-text { fill: rgb(51, 135, 163); stroke: rgb(51, 135, 163); } #mermaid-rlk-r1 .edge-thickness-normal { stroke-width: 1px; } #mermaid-rlk-r1 .edge-thickness-thick { stroke-width: 3.5px; } #mermaid-rlk-r1 .edge-pattern-solid { stroke-dasharray: 0; } #mermaid-rlk-r1 .edge-thickness-invisible { stroke-width: 0; fill: none; } #mermaid-rlk-r1 .edge-pattern-dashed { stroke-dasharray: 3; } #mermaid-rlk-r1 .edge-pattern-dotted { stroke-dasharray: 2; } #mermaid-rlk-r1 .marker { fill: rgb(145, 145, 141); stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 .marker.cross { stroke: rgb(145, 145, 141); } #mermaid-rlk-r1 svg { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 16px; } #mermaid-rlk-r1 p { margin: 0px; } #mermaid-rlk-r1 .label { font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; color: rgb(25, 25, 25); } #mermaid-rlk-r1 .cluster-label text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster-label span p { background-color: transparent; } #mermaid-rlk-r1 .label text, #mermaid-rlk-r1 span { fill: rgb(25, 25, 25); color: rgb(25, 25, 25); } #mermaid-rlk-r1 .node rect, #mermaid-rlk-r1 .node circle, #mermaid-rlk-r1 .node ellipse, #mermaid-rlk-r1 .node polygon, #mermaid-rlk-r1 .node path { fill: rgb(240, 240, 235); stroke: rgb(217, 216, 213); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label text, #mermaid-rlk-r1 .node .label text, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-anchor: middle; } #mermaid-rlk-r1 .node .katex path { fill: rgb(0, 0, 0); stroke: rgb(0, 0, 0); stroke-width: 1px; } #mermaid-rlk-r1 .rough-node .label, #mermaid-rlk-r1 .node .label, #mermaid-rlk-r1 .image-shape .label, #mermaid-rlk-r1 .icon-shape .label { text-align: center; } #mermaid-rlk-r1 .node.clickable { cursor: pointer; } #mermaid-rlk-r1 .root .anchor path { stroke-width: 0; stroke: rgb(145, 145, 141); fill: rgb(145, 145, 141) !important; } #mermaid-rlk-r1 .arrowheadPath { fill: rgb(11, 11, 11); } #mermaid-rlk-r1 .edgePaths .path { stroke: rgb(145, 145, 141); stroke-width: 1px; } #mermaid-rlk-r1 .flowchart-link { stroke: rgb(145, 145, 141); fill: none; } #mermaid-rlk-r1 .edgeLabel { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .edgeLabel p { background-color: rgb(245, 230, 216); } #mermaid-rlk-r1 .edgeLabel rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .labelBkg { background-color: rgba(245, 230, 216, 0.5); } #mermaid-rlk-r1 .cluster rect { fill: rgb(204, 120, 92); stroke: rgb(138, 115, 107); stroke-width: 1px; } #mermaid-rlk-r1 .cluster text { fill: rgb(51, 135, 163); } #mermaid-rlk-r1 .cluster span { color: rgb(51, 135, 163); } #mermaid-rlk-r1 .node .collapsed-indicator { fill: rgb(138, 115, 107); stroke: none; opacity: 0.6; } #mermaid-rlk-r1 .node .collapsed-separator { stroke: rgb(138, 115, 107); stroke-width: 0.75px; } #mermaid-rlk-r1 div.mermaidTooltip { position: absolute; text-align: center; max-width: 200px; padding: 2px; font-family: system-ui, “Segoe UI”, Roboto, Helvetica, Arial, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, “Kohinoor Devanagari”, “Kohinoor Bangla”, “Kohinoor Telugu”, “Tamil Sangam MN”, “Kohinoor Gujarati”, “Malayalam Sangam MN”, “Nirmala UI”, “Noto Sans Devanagari UI”, “Noto Sans Devanagari”, “Noto Sans Bengali UI”, “Noto Sans Bengali”, “Noto Sans Telugu UI”, “Noto Sans Telugu”, “Noto Sans Tamil UI”, “Noto Sans Tamil”, “Noto Sans Gujarati UI”, “Noto Sans Gujarati”, “Noto Sans Kannada UI”, “Noto Sans Kannada”, “Noto Sans Malayalam UI”, “Noto Sans Malayalam”, Thonburi, “Leelawadee UI”, “Noto Sans Thai UI”, “Noto Sans Thai”, Kefa, Ebrima, “Noto Sans Ethiopic”, “Abyssinica SIL”, sans-serif, ui-sans-serif, system-ui, -apple-system, “Segoe UI”, Roboto, “PingFang SC”, “PingFang TC”, “Hiragino Sans”, “Apple SD Gothic Neo”, sans-serif; font-size: 12px; background: rgb(204, 120, 92); border: 1px solid rgb(138, 115, 107); border-radius: 2px; pointer-events: none; z-index: 100; } #mermaid-rlk-r1 .flowchartTitleText { text-anchor: middle; font-size: 18px; fill: rgb(25, 25, 25); } #mermaid-rlk-r1 rect.text { fill: none; stroke-width: 0; } #mermaid-rlk-r1 .icon-shape, #mermaid-rlk-r1 .image-shape { background-color: rgb(245, 230, 216); text-align: center; } #mermaid-rlk-r1 .icon-shape p, #mermaid-rlk-r1 .image-shape p { background-color: rgb(245, 230, 216); padding: 2px; } #mermaid-rlk-r1 .icon-shape .label rect, #mermaid-rlk-r1 .image-shape .label rect { opacity: 0.5; background-color: rgb(245, 230, 216); fill: rgb(245, 230, 216); } #mermaid-rlk-r1 .label-icon { display: inline-block; height: 1em; overflow: visible; vertical-align: -0.125em; } #mermaid-rlk-r1 .node .label-icon path { fill: currentcolor; stroke: revert; stroke-width: revert; } #mermaid-rlk-r1 .node .neo-node { stroke: rgb(217, 216, 213); } #mermaid-rlk-r1 [data-look=”neo”].node rect, #mermaid-rlk-r1 [data-look=”neo”].cluster rect, #mermaid-rlk-r1 [data-look=”neo”].node polygon { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].swimlane.cluster rect { filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node path { stroke: url(“#mermaid-rlk-r1-gradient”); stroke-width: 1px; } #mermaid-rlk-r1 [data-look=”neo”].node .outer-path { filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node .neo-line path { stroke: rgb(217, 216, 213); filter: none; } #mermaid-rlk-r1 [data-look=”neo”].node circle { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].node circle .state-start { fill: rgb(0, 0, 0); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon { fill: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 [data-look=”neo”].icon-shape .icon-neo path { stroke: url(“#mermaid-rlk-r1-gradient”); filter: drop-shadow(rgb(185, 185, 185) 1px 2px 2px); } #mermaid-rlk-r1 :root { –mermaid-font-family: system-ui,”Segoe UI”,Roboto,Helvetica,Arial,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,”Kohinoor Devanagari”,”Kohinoor Bangla”,”Kohinoor Telugu”,”Tamil Sangam MN”,”Kohinoor Gujarati”,”Malayalam Sangam MN”,”Nirmala UI”,”Noto Sans Devanagari UI”,”Noto Sans Devanagari”,”Noto Sans Bengali UI”,”Noto Sans Bengali”,”Noto Sans Telugu UI”,”Noto Sans Telugu”,”Noto Sans Tamil UI”,”Noto Sans Tamil”,”Noto Sans Gujarati UI”,”Noto Sans Gujarati”,”Noto Sans Kannada UI”,”Noto Sans Kannada”,”Noto Sans Malayalam UI”,”Noto Sans Malayalam”,Thonburi,”Leelawadee UI”,”Noto Sans Thai UI”,”Noto Sans Thai”,Kefa,Ebrima,”Noto Sans Ethiopic”,”Abyssinica SIL”,sans-serif,ui-sans-serif,system-ui,-apple-system,”Segoe UI”,Roboto,”PingFang SC”,”PingFang TC”,”Hiragino Sans”,”Apple SD Gothic Neo”,sans-serif; }API GatewayAuth ServiceOrder ServiceOrder DBNotification ServiceUser DB

Este diagrama da Sereia reside no repositório, juntamente com o código que representa. Quando um desenvolvedor adiciona um novo serviço, ele atualiza este arquivo na mesma solicitação de pull request. A revisão de código inclui a alteração do diagrama. A documentação e o código são compartilhados.

O que os diagramas como código não resolvem:

Não resolve o problema da documentação de sistemas legados. Um programa COBOL adicionado a uma biblioteca de mainframe por um desenvolvedor que envia um JCL compilado em vez de uma solicitação de pull do Git não aciona uma atualização de arquivo do Mermaid. O processo de gerenciamento de mudanças do mainframe e o processo de documentação baseado em Git são sistemas separados, sem sincronização automática.

Isso não resolve o problema da precisão excessiva. Um diagrama Mermaid que precisa ser atualizado manualmente para cada novo serviço ainda exige a disciplina humana que o processo deveria substituir. Se a atualização do diagrama for uma etapa manual, ela será omitida.

Não corrige retroativamente diagramas legados. Para um portfólio COBOL sem documentação legível por máquina existente, o modelo de diagramas como código fornece uma estrutura para documentação futura, mas não gera a documentação atual.

A abordagem de análise estrutural para sistemas legados

Para sistemas legados onde diagramas como código são impraticáveis, seja porque o fluxo de trabalho de desenvolvimento não passa pelo Git, porque a documentação existente está muito desatualizada para servir como ponto de partida para uma abordagem baseada em texto, ou porque a base de código nunca foi formalmente documentada, a análise estrutural do código é o único mecanismo que produz documentação atual e precisa a partir do zero.

A análise estrutural examina o código propriamente dito — programas COBOL, fluxos de tarefas JCL, copybooks, SQL incorporado — e deriva as relações de dependência, os inventários de programas e as estruturas de dados diretamente do conteúdo do código. O resultado não é um diagrama desenhado por um humano que compreendeu o código; é um diagrama derivado algoritmicamente do próprio código. Sua precisão é limitada pela precisão da análise, e não pela memória do desenvolvedor que o criou.

O fluxo de trabalho:

bater

# Structural analysis pipeline for COBOL documentation
# Step 1: Parse all COBOL source in the portfolio
smart-ts-xl analyze --source /cobol/src --output /docs/analysis/

# Step 2: Generate dependency graph (always current)
smart-ts-xl diagram --type dependency-graph \
    --format mermaid \
    --output /docs/dependency-graph.md

# Step 3: Generate program inventory (always current)
smart-ts-xl report --type program-inventory \
    --format markdown \
    --output /docs/program-inventory.md

# Step 4: Diff against previous analysis (detect what changed)
smart-ts-xl diff \
    --baseline /docs/analysis/2026-09-01/ \
    --current  /docs/analysis/2026-10-01/ \
    --output   /docs/changes/delta-report.md

O relatório delta, a diferença entre duas análises consecutivas, é o registro de alterações que a proveniência estática do diagrama produz automaticamente. Programas adicionados, programas removidos, dependências alteradas, copybooks modificados: tudo aparece no relatório delta sem qualquer esforço de documentação humana.

O diagrama gerado pela última análise representa a documentação atualizada até a data da análise. Executar a análise de forma programada, semanalmente ou acionada por cada promoção de produção, gera documentação atualizada em uma cadência definida, sem a necessidade de trabalho manual contínuo de documentação.

O Quadro de Prevenção de Documentação

Prevenir a dívida documental exige abordar os cinco mecanismos de obsolescência com práticas específicas e implementáveis:

Contra o problema do acúmulo de delta:

  • Estabeleça uma frequência de análise: semanal para sistemas de alta velocidade, mensal para sistemas estáveis.
  • Gere a documentação a partir do código em cada execução de análise, e não manualmente.
  • Gere um relatório de alterações para cada execução, mostrando o que mudou desde a última análise.

Contra o problema da falta de proveniência:

  • Cada diagrama inclui a sua fonte de geração (data e versão da análise do código).
  • Nunca publique um diagrama sem registrar como e quando ele foi produzido.
  • Armazene os diagramas gerados juntamente com os resultados das análises que os produziram.

Contra o problema da deriva da propriedade:

  • A geração de documentação é uma etapa do processo, não uma responsabilidade individual.
  • A documentação pertence ao oleoduto; a saída de qualquer indivíduo não a invalida.
  • A documentação gerada não tem proprietário para se desviar.

Contra o problema da precisão excessiva:

  • Defina o nível de abstração apropriado para cada tipo de diagrama antes de criá-lo.
  • Diagramas de inventário de componentes no nível de serviço/programa, não no nível de função.
  • Diagramas de relacionamento no nível do limite do domínio, não no nível da chamada individual.
  • Os diagramas detalhados (gráficos de chamadas, esquemas de dados) são gerados automaticamente, e não desenhados à mão.

Contra o problema de dependência de formato:

  • Diagramas gerados em formatos baseados em texto (Mermaid, GraphViz DOT, SVG)
  • Não existe documentação de arquitetura apenas em Visio, PowerPoint ou PDF.
  • Os diagramas são armazenados em um sistema de controle de versão juntamente com o código que documentam.

Como SMART TS XL Aborda dívidas de documentação legadas

Para portfólios legados de COBOL e mainframe, SMART TS XL é o mecanismo de análise estrutural que torna possível a documentação baseada em evidências e que faz com que "regenerar a partir do código" seja uma alternativa prática a "atualizar o diagrama do SharePoint de 2009".

A funcionalidade de análise estática de código examina cada programa COBOL, copybook, fluxo de trabalho JCL e instrução SQL incorporada para gerar o inventário de programas, métricas de complexidade e identificação de código morto, que formam a base de qualquer documentação legada precisa. Esse inventário é a substituição baseada em evidências para a lista de programas mantida manualmente, que está sempre incompleta, sempre desatualizada e sempre incorreta de maneiras desconhecidas.

O mapeamento de dependências da aplicação gera o grafo de dependências, incluindo cada relação de chamada (CALL), cada relação de cópia (COPY), cada fluxo de dados entre programas, sendo este o artefato central da documentação da arquitetura. Esse grafo é regenerado a partir do código a cada execução da análise, produzindo um diagrama de dependências atualizado até a última análise, sem qualquer intervenção humana de documentação entre as execuções.

A funcionalidade de análise de impacto gera a documentação delta: quando uma alteração é feita no código-fonte, a análise de impacto identifica tudo o que mudou em relação ao estado anterior. Este é o relatório delta automatizado que aborda o problema do acúmulo de alterações, capturando e documentando automaticamente cada mudança que poderia ter ampliado a discrepância entre o diagrama e a realidade.

A funcionalidade de busca corporativa torna a documentação consultável: encontre todos os programas que chamam um subprograma específico (o fragmento do grafo de chamadas de um componente), todos os programas que incluem um copybook específico (o escopo de dependência de um componente compartilhado), todos os programas modificados após uma data específica (o registro de alterações de um determinado período). Essa funcionalidade de busca é a interface da documentação, a ferramenta que responde a perguntas sobre o estado atual do sistema a partir da análise atual, e não de um diagrama estático que pode estar desatualizado há anos.

Para organizações que realizam modernização legada programas, SMART TS XLA geração da documentação é a etapa prévia necessária: o diagrama de dependências, o inventário do programa e a documentação do esquema de dados que o programa de modernização precisa para definir o escopo, sequenciar as ondas de migração e validar os resultados. Essa documentação não pode vir do arquivo do SharePoint. Ela deve vir do código.

O único diagrama preciso é aquele derivado do código.

O diagrama de arquitetura de 2009 na página do SharePoint continuará existindo até que alguém o exclua explicitamente. Ele continuará sendo enviado a novos desenvolvedores quando perguntarem como o sistema funciona. Continuará influenciando decisões sobre um sistema que já não descreve com precisão. A lacuna entre o diagrama e o sistema continuará aumentando a cada commit, a cada implantação, a cada adição e descontinuação de programa.

A alternativa não é "atualizar os diagramas com mais frequência". Processos que exigem disciplina humana para manutenção em um código que muda continuamente têm um modo de falha conhecido: a disciplina falha. A alternativa é uma documentação derivada do código, que usa o código como fonte de verdade, que se regenera automaticamente quando o código muda e que carrega o registro de data e hora da análise, informando a cada leitor exatamente o quão atualizada ela está.

Para sistemas modernos em nuvem, diagramas como código e ferramentas de documentação viva oferecem essa possibilidade. Para sistemas COBOL legados, a análise estrutural do código a fornece. O mecanismo difere; o princípio é o mesmo: o diagrama é preciso quando derivado do código e acumula dívida técnica a partir do momento em que é separado do código que o gerou.

O único diagrama que permanece atual é o diagrama que foi desenhado pelo código.