Exemplo Manifesto

O que é exemplo manifesto e por que isso importa na prática

Eu sei que esse termo não aparece em muitos lugares de forma clara. Quando você procura no Google, acha uns resultados fragmentados e fóruns com dúvidas de gente que também tá perdida. Vou explicar do jeito que eu aprendi, depois de bater cabeça com isso em projetos reais.

Definição básica de exemplo manifesto

Um exemplo manifesto é aquele caso tão claro, tão evidente, que não precisa de justificativa longa. Você apresenta ele como referência direta porque todo mundo reconhece o padrão. Não é teoria abstrata, é um objeto concreto que serve de base pra comparação. No direito brasileiro, por exemplo, se fala muito disso. Um documento assinado digitalmente com certificado A1 tem exemplo manifesto na legislação específica que regula isso. Ou seja: tem um caso concreto escrito na lei que serve de parâmetro seguro.

Isso aparece também fora do direito. Em programacao, quando você documenta uma biblioteca e mostra um exemplo manifesto de uso, as pessoas entendem direto sem precisar ler tres paginas de explicacao. Um bloco de codigo simples fazendo exatamente o que voce diz que faz.

Como criar um exemplo manifesto funcional

Primeiro, escolha algo que realmente funcione. Nao adianta colocar um exemplo que nunca foi testado. Eu vi muita gente errar isso. Colocam um trecho copiado de algum forum e depois quando o usuario tenta usar, simplesmente nao funciona. O exemplo manifesto tem que ser validado no mundo real antes de virar referencia. Segundo, mantenha ele minimalista. Quanto menos linhas, melhor. Se voce precisa de duzentas linhas pra demonstrar algo, voce ainda nao entendeu o assunto o suficiente. Um exemplo manifesto ideal cabe em sessenta linhas no maximo. Se passar disso, divida em versoes mais simples.

Terceiro, inclua todos os passos necessários. Esse é um erro comum que eu cometi no passado. Eu postava um exemplo manifesto e esquecia de mencionar que o usuario precisava de uma biblioteca X instalada ou de um arquivo de configuracao Y. A pessoa copiava o codigo e dai dava erro, e eu levava bronca feia. Agora eu sempre sigo esse padrao:

Lista de requisitos antes do exemplo. Versao minima necessaria de cada dependencia. Comando exato pra instalar se preciso. O codigo em si. E depois um paragrafo curto explicando o que cada parte faz.

Problema real que eu encontrei e como resolvi

Num projeto interno da empresa em que eu trabalhava, precisavamos documentar um fluxo de autenticacao com tokens JWT. O exemplo manifesto que eu escrevi inicialmente funcionava no meu computador mas falhava nos ambientes de teste dos colegas. O problema era sutil: meu código usava uma variavel de ambiente que estava configurada no meu perfil mas nao nos outros. A solucao foi simples mas demorou pra eu perceber. Eu adicionei um arquivo .env.example com todas as variaveis necessarias e um comentario explicando o que cada uma fazia. Coloquei esse arquivo no mesmo nivel do exemplo manifesto. Depois disso, zero problemas nos testes.

Isso mudou completamente a qualidade dos meus exemplos. Antes eu achava que so o codigo bastava. Agora eu entendo que o contexto do exemplo manifesto é tao importante quanto o proprio codigo.

Dica avançada: quando o exemplo manifesto falha

Tem situacao em que o exemplo manifesto simplesmente nao serve. Isso acontece quando o caso de uso é muito especifico ou depende de condicoes que o exemplo padrao nao cobre. Nesses casos, forcar um exemplo manifesto gera mais confusao do que utilidade. O que eu faço nesses momentos é criar duas camadas. Um exemplo manifesto basico que mostra o funcionamento geral. E depois um section separado com casos de borda. Não misturo as duas coisas no mesmo bloco. Se misturar, quem ta lendo nao consegue distinguir o que é essencial do que é excecao.

Tambem é bom saber quando nao criar exemplo manifesto. Se o seu produto tem duzias de opcoes configuraveis, cada uma delas gerando combinacoes possiveis, ai um unico exemplo jamais vai cobrir tudo. Melhor documentar bem os parametros e deixar o usuario montar seu proprio exemplo baseado na sua explicacao.

Exemplo manifesto aplicado na pratica

Pra fechar, vou dar um exemplo bem concreto de como isso funciona no dia a dia. Suponha que voce esta criando uma API REST simples. O exemplo manifesto mais util seria uma requisição GET que retorna um JSON com dados basicos. Nada de autenticacao, nada de paginação, só o nucleo.

GET /api/usuarios HTTP/1.1
Host: exemplo.com.br

Resposta:
{
  "id": 1,
  "nome": "João Silva",
  "email": "joao@exemplo.com.br"
}

A partir dali, qualquer coisa extra que o usuario precise construir sobre esse fundamento. Autenticacao, filtros, paginacao. Se o exemplo manifesto funcionar, o resto segue junto. Se falhar nessa base, tudo que vier depois também vai falhar. E isso é praticamente tudo. O resto é ajustar o metodo as suas necessidades especificas e validar antes de publicar. Nao confie em exemplos que voce mesmo nao testou. Isso é a regra mais importante que eu aprendi.