Representar Por Meio De Escrita

Por que escrever é mais preciso do que diagramar

A maioria das pessoas tenta representar sistemas complexos usando apenas diagramas UML ou fluxogramas visuais. O problema é que diagramas escondem ambiguidades. Eles parecem claros até o momento em que alguém precisa implementar e descobre que três decisões críticas ficaram subentendidas. Representar por meio de escrita força você a decidir cada detalhe antes de qualquer desenho. O processo funciona assim: pegue uma decisão, qualquer decisão, e escreva-a como um parágrafo curto em linguagem natural, mas com restrições explícitas. Não use termos vagos como "geralmente", "pode ser" ou "caso necessário". Se você não consegue definir uma regra fixa em texto, significa que ainda não entendeu o problema o suficiente para avançar. Aqui está um exemplo real do tipo de coisa que eu escrevo. Para um serviço de autenticação, em vez de um diagrama de sequência, eu produzo este texto:

Regra de login com MFA: Quando um usuário insere credenciais válidas, o sistema gera um token OTP de 6 dígitos com validade de 180 segundos e envia via SMS ao número cadastrado. O token é descartado após três tentativas fracassadas. O usuário pode solicitar um novo token a cada 60 segundos. Se o login falhar por cinco vezes consecutivas em 10 minutos, a conta é bloqueada automaticamente e uma notificação é enviada para o email de segurança do usuário. O bloqueio expira após 30 minutos sem necessidade de intervenção humana. Isso leva cerca de três minutos para escrever. Um diagramas equivalente levaria vinte minutos e ainda assim omitiria detalhes como o período de 60 segundos entre solicitações de novo token. Quem lê esse parágrafo sabe exatamente o que implementar. Quem olha só o diagrama vai ter que adivinhar.

Por que isso funciona melhor do que o esperado

A escrita elimina a ilusão de clareza. Diagramas criam uma sensação de precisão porque organizam informações visualmente, mas a organização visual não substitui a definição precisa. Você pode ter o diagrama de classes mais bonito do mundo e ainda assim ter classes que não definem quem é responsável por quê. Outro ponto que muita gente não considera: representação textual é significativamente mais fácil de versionar. Arquivos de diagrama, especialmente os gerados por ferramentas proprietárias, são binários ou XMLs difíceis de comparar. Um documento de texto entra perfeitamente em diff. Mudanças ficam visíveis linha por linha. Eu já passei duas horas tentando entender o que mudou entre duas versões de um diagrama no Enterprise Architect porque o diff mostrava apenas "arquivo alterado".

Limitações que ninguém menciona

Representar por meio de escrita não é solução para tudo. Diagramas visuais ainda são superiores para comunicação com stakeholders não técnicos. Um executivo ou um cliente frequentemente precisa ver um fluxo de alto nível para dar feedback útil. Texto puro afasta esse público. Também existe um ponto de saturação. Para sistemas com dezenas de entidades e centenas de regras de negócio, o texto solto se torna ingestável muito rápido. Nesse cenário, a abordagem híbrida funciona melhor: texto para regras e definições precisas, diagramas apenas como complemento visual para contextos específicos. A regra é simples. Se o diagrama não adiciona informação que o texto não transmite, não desenhe. Um caso específico que encontrei recentemente foi com regras de preço dinâmico para uma plataforma de e-commerce. Escrevi todas as regras de forma textual conforme o método descrito acima. Quando cheguei à regra de desconto progressivo baseado em volume, percebi que o texto estava ficando ambíguo apesar dos esforços. A ambiguidade estava na interação entre três condições: faixa de volume, categoria do produto e tempo de vigência da promoção. Resolvi criando uma tabela simples em formato CSV anexada ao documento textual, não um diagrama. A tabela tinha quatro colunas e onze linhas. Leu-se em 30 segundos e ficou livre de ambiguidade. O que um diagrama teria levado meia hora para representar visualmente, e mesmo assim com risco de interpretação errada.

Representar por meio de escrita na prática

O que separa um texto útil de um texto inútil é a presença de restrições quantificáveis. Frases como "o sistema deve responder rapidamente" são ruins. Frases como "o sistema deve retornar resposta em no máximo 200ms para requisições sob carga normal de até 500 requisições por segundo" são boa. A diferença é que a segunda frase pode ser testada. A primeira só gera discussões infinitas em revisão de código. Use a seguinte verificação prática após escrever qualquer regra textual: leia para alguém que não esteja envolvido no projeto e peça para essa pessoa implementar exatamente o que você escreveu. Se ela tiver mais de três perguntas, seu texto ainda não está pronto. Esse teste leva cinco minutos e evita semanas de retrabalho. O formato mais eficiente que eu encontrei segue esta estrutura básica para cada regra ou decisão:

Condição: quando acontece X. Ação: o sistema faz Y. Restrição: Y só ocorre se Z for verdadeiro.

Caso limite: quando W acontece, o comportamento é V. Isso não é rígido. Às vezes você não tem um caso limite claro e isso é informação também. Anotar "sem caso limite identificado" já diz algo para o leitor.

Ferramentas que realmente importam

Você não precisa de nada especial. Um editor de texto comum com formatação markdown ou simples é suficiente. O importante não é a ferramenta, é o hábito de escrever com precisão antes de diagramar. Muitos desenvolvedores pulam direto para o diagrama porque parece mais produtivo. Não é. Diagramar sem regra textual definida é desenhar suposições, não arquitetura. Se você quer um ponto de partida concreto, comece escolhendo um único componente do seu sistema atual e transforme todas as suas regras em texto seguindo o formato acima. Leva cerca de 40 minutos para um componente médio. O resultado costuma revelar pelo menos três decisões que estavam indefinidas e que você estava operando no piloto automático achando que sabia o que deveria acontecer.