Discrição E Descrição

O equilíbrio entre ser sucinto e ser completo

Muita gente confunde discrição com descrição porque os termos parecem semelhantes, mas na prática eles representam estratégias opostas de comunicação. Discrição é sobre economia de informação. Descrição é sobre expansão. O problema é que a maioria das pessoas não sabe quando aplicar cada uma, e escreve documentação, manuais ou especificações técnicas como se os dois fossem a mesma coisa. Isso gera retrabalho constante.

Discrição e descrição: o que realmente significa cada uma

Discrição, neste contexto, se refere à capacidade de identificar e comunicar apenas o necessário. Não é sobre omitir deliberadamente — é sobre filtrar. Um sistema de log bem configurado, por exemplo, não registra cada caractere processado. Ele registra eventos significativos. Quando eu comecei a trabalhar com arquitetura de software, meu primeiro erro foi escrever especificações que listavam cada parâetro possível de uma API, mesmo os que tinham valor padrão. A documentação ficou com 47 páginas. Ninguém lia. Descrição é o oposto. É detalhar, contextualizar, exemplificar. Quando você está documentando algo novo para alguém que não conhece o domínio, precisa descrever. Mas a diferença fundamental é que descrição sem discrição vira ruído, e discrição sem descrição vira ambiguidade.

Como decidir qual usar em cada situação

Existe uma lógica simples que costuma funcionar, mas ela depende do seu público. Se quem vai ler sua documentação já domina o assunto, discrição é a resposta. Especifique interfaces, não implementações. Liste contratos, não intenções. Para leitores inexperientes, a coisa muda — aí sim você descreve. Mostre exemplos, explique o porquê das escolhas, detalhe o fluxo. Onde as pessoas erram é no meio do caminho. Escrevem para iniciantes mas com linguagem de especialista, ou escrevem para especialistas mas com explicação de manual de usuário. Uma vez, num projeto interno, precisei documentar um microserviço de autenticação. A primeira versão tinha três capítulos explicando JWT. A segunda versão, totalmente discria, simplesmente listava os endpoints, os headers esperados e os códigos de retorno. Colegas mais experientes passaram a usar a segunda versão como referência rápida. A primeira foi arquivada em duas semanas.

A regra prática é esta: pergunte-se antes de escrever se o leitor precisa saber o contexto ou apenas o que fazer. Se for o segundo caso, seja discrio. Se for o primeiro, descreva sem moderação.

Pegadinhas que ninguém comenta

Uma coisa que aprendi na prática e que raramente aparece em guias teóricos é que discrição e descrição não são Fixas — elas variam com o tempo. O que era descrição necessária hoje pode virar discrição amanhã, conforme o conhecimento da equipe se consolida. Manter documentação viva significa revisar periodicamente o nível de detalhe, não apenas corrigir erros. Outro ponto que custa caro: a falsa sensação de que ser discrio é ser vago. Discrição bem aplicada ainda é exata. "Retorna 401 quando o token expira" é discrio e preciso. "Retorna um erro se algo estiver errado" é vago, não discrio. A diferença é abismal para quem precisa implementar ou depurar.

Também vale mencionar que ferramentas de geração automática de documentação muitas vezes falham justamente aqui. Elas tendem a descrever tudo, porque extraem diretamente do código. Annotations, JSDoc, TypeDoc — todos produzem documentos volumosos que misturam discrição e descrição sem Critério. A solução não é abandonar essas ferramentas, mas sim adicionar uma camada de Curadoria pós-geração. Eu costumo revisar manualmente qualquer documentação gerada automaticamente que ultrapasse duas páginas por módulo.

Quando nenhuma das duas funciona

Existe um cenário onde discrição e descrição são insuficientes: problemas de integração entre sistemas heterogêneos. Nestes casos, nem ser sucinto nem ser detalhado resolve. O que funciona é um artefato intermediário — um protocolo de contrato, um schema validável, um teste de integração como fonte de verdade. Já vi times tentarem documentar integrações complexas apenas com texto descritivo. Resultado: documentação desatualizada em semanas porque ninguém atualizava o documento textual quando o código mudava. Se o seu problema envolve comunicação entre sistemas diferentes, considere gerar a documentação a partir de contratos executáveis. OpenAPI, GraphQL schema, Protocol Buffers — essas definições são simultaneamente descrição completa e discrição operacional, porque são código, não prose.

Um resumo prático para aplicar agora

Antes de escrever qualquer documento técnico, classifique seu público em uma das três categorias: iniciante, praticante ou especialista. Para iniciantes, descreva com exemplos e contexto. Para praticantes, equilibre — descreva o que é novo, seja discrio no que é conhecido. Para especialistas, seja predominantemente discrio, confiando no conhecimento de base deles. Reveja o documento após 30 dias. Se ninguém fizer perguntas sobre o conteúdo, provavelmente estava discrio demais. Se todo mundo pedir esclarecimentos, estava descritivo demais. O ajuste fino é contínuo, não um evento único.