Documentar uso, limitações e decisões da aplicação

Quem recebe sua aplicação não deve precisar explorar a pasta de desenvolvimento para descobrir o que ela faz. O README é o ponto de entrada: apresenta a finalidade, orienta o uso, indica onde encontrar limites relevantes e aponta documentos complementares.

Neste tutorial, usaremos um caso didático: uma CLI fictícia chamada csv-resumo, que lê um CSV e mostra um resumo de suas colunas numéricas. Os comandos, arquivos e saídas desse caso são simulados; eles servem para estruturar a documentação e não representam um pacote disponível para instalação.

Cada documento atende a uma pergunta e um público principal.

Use # e ## para criar uma hierarquia escaneável; listas para requisitos ou observações; links relativos para documentos do próprio repositório; e blocos cercados por crases triplas para separar comandos e resultados da explicação.

O leitor deve distinguir imediatamente o que é texto explicativo, o que deve ser digitado e o que é uma saída esperada.

Exemplo didático: o conteúdo abaixo documenta a CLI fictícia csv-resumo.

O README pode apontar para documentos mais específicos, mas não precisa duplicá-los. Docstrings explicam o uso de partes do código; instruções de desenvolvimento ajudam quem altera o projeto; registros de decisão preservam o porquê de escolhas relevantes. A pessoa usuária encontra no README apenas o contexto necessário para usar a entrega.

Um início rápido responde às primeiras dúvidas de quem recebeu a distribuição: qual artefato e versão estão sendo documentados, onde obtê-lo, quais recursos precisa ter e quais comandos executar para confirmar que a aplicação funciona.

Não suponha que o pacote esteja publicado em um índice público. Se a entrega é uma wheel fornecida pela equipe, declare isso. Também diferencie o uso normal de comandos de desenvolvimento: pip install pacote.whl instala uma distribuição; pip install -e . depende das fontes e não serve como instrução de uso da entrega.

A sequência deve partir de um ambiente limpo e terminar em um resultado observável.

Em um README, marque claramente o que a pessoa deve digitar e o que deve aparecer depois. Um exemplo útil inclui o conteúdo do arquivo de entrada, para que ninguém precise inventar dados ou procurar arquivos no repositório.

O caso abaixo é didático e simulado. Troque o nome da wheel, o comando e os resultados pelos elementos do seu próprio artefato validado; ele não anuncia um pacote disponível para instalação.

Exemplo de Markdown para adaptar ao seu artefato.

Uma referência de configuração não deve obrigar o usuário a inferir nomes ou padrões. Para cada opção, registre: finalidade, tipo, padrão, valores aceitos e o nome usado em cada fonte.

Considere este contrato didático de uma CLI de resumo de CSV chamada csv-resumo:

| Opção | Finalidade e tipo | Padrão | CLI | Ambiente | Arquivo TOML |
| --- | --- | --- | --- | --- | --- |
| diretório de dados | Pasta que contém os CSVs; caminho | diretório atual | --dados CAMINHO | CSV_RESUMO_DADOS | dados.dir |
| separador | Delimitador do CSV; texto de 1 caractere | , | --separador CARACTERE | CSV_RESUMO_SEPARADOR | dados.separador |
| máximo de linhas | Limite de linhas lidas; inteiro positivo | 1000 | --max-linhas N | CSV_RESUMO_MAX_LINHAS | processamento.max_linhas |

Liste somente fontes que a aplicação realmente aceita. Não invente uma variável de ambiente, uma chave ou um valor alternativo para tornar a tabela “mais completa”.

A presença de uma fonte e o valor que ela fornece são informações diferentes.

Para este contrato didático, a maior prioridade vence: argumento da CLI → variável de ambiente → arquivo TOML → padrão interno. Se uma fonte não informar uma opção, ela apenas cede lugar à próxima; isso não equivale a fornecer um valor.

Declare também onde o arquivo fica e como é selecionado. Exemplo de texto para a referência:

Sem --config, csv-resumo procura opcionalmente config.toml no diretório atual. Para usar outro arquivo, informe --config CAMINHO. Caminhos relativos nas chaves dados.dir são resolvidos a partir da pasta que contém o próprio arquivo TOML. Já caminhos passados em --dados são resolvidos a partir do diretório atual do terminal.

Assim, o usuário sabe tanto qual fonte vence quanto qual pasta serve de base para cada caminho.

Salve este conteúdo como config.toml fora do pacote instalado, por exemplo em uma pasta de trabalho do usuário. Se ele não estiver no diretório atual, selecione-o com --config.

Neste exemplo, entrada é interpretado em relação à pasta que contém config.toml. O caminho do arquivo de dados não é uma pasta interna da instalação.

A referência deve cobrir as situações previstas pelo contrato, com linguagem objetiva:

• Arquivo padrão opcional ausente: a aplicação continua usando ambiente e padrões internos.
• Arquivo indicado por --config inexistente: a execução não continua; informe o caminho solicitado e oriente o usuário a corrigir o caminho ou criar o arquivo.
• Valor inválido: a execução não inicia a operação. Por exemplo, max_linhas = 0 viola o requisito de inteiro positivo; informe a opção e o valor esperado.

Não inclua credenciais, tokens ou caminhos pessoais nos exemplos. Use valores fictícios e caminhos relativos. A tabela detalhada de mensagens e códigos de saída será tratada em outra seção da documentação.

Documente falhas pela situação que a pessoa consegue observar, e não pela exceção interna. Para cada situação, registre:

• condição: quando ocorre;
• mensagem relevante: o texto ou trecho que ajuda a reconhecer o problema;
• canal: stdout ou stderr;
• código de saída: o valor definido pelo contrato da aplicação;
• ação recomendada: o próximo passo concreto.

Códigos não zero não têm significado universal. Por isso, descreva somente os códigos que a sua aplicação definiu.

A referência conecta o resultado técnico observável a uma recuperação segura.

Em exemplos de terminal, identifique visualmente o comando, o resultado normal em stdout e o diagnóstico em stderr. Isso evita que o usuário copie uma mensagem de erro como se fosse parte do comando ou espere uma falha no canal errado.

Na documentação da versão entregue, separe afirmações que parecem semelhantes, mas respondem a perguntas diferentes:

• Compatibilidade declarada: o intervalo aceito pelos metadados da distribuição, como requires-python.
• Combinações verificadas: versões de Python e plataformas nas quais o artefato foi realmente testado.
• Limite imposto: uma restrição aplicada pela própria aplicação, por exemplo, recusar um arquivo acima de um tamanho definido.
• Volume observado: o maior caso usado em uma avaliação; ele não vira limite nem garantia automaticamente.

Ambientes não avaliados devem permanecer como não avaliados. A falta de teste não prova incompatibilidade, mas também não prova funcionamento.

Use uma matriz para tornar visível a diferença entre metadado, teste e ausência de evidência.

Para cada item, registre a condição em que ocorre, o impacto para o usuário e uma alternativa quando ela existir.

• Limite imposto pela aplicação: é aplicado de forma consistente pelo programa. Documente o valor, a condição e a mensagem ou efeito esperado.
• Restrição conhecida: comportamento ou cenário reconhecido que afeta o uso, mas não necessariamente é bloqueado pelo programa.
• Maior volume observado: descreve somente o caso avaliado; não é capacidade máxima garantida.
• Exclusão de escopo: deixa claro o que a aplicação não se propõe a fazer e quais garantias não oferece.

Um ADR (Architecture Decision Record, ou registro de decisão arquitetural) explica por que uma escolha relevante foi feita. Ele não substitui docstrings, não lista todas as classes e não descreve o código linha a linha.

Use um ADR quando a escolha cria uma fronteira, impõe uma dependência, descarta alternativas plausíveis ou terá consequências para mudanças futuras. No caso da CLI de resumo de CSV, separar a leitura de CSV das regras de resumo é uma decisão digna de registro.

O diagrama mostra uma decisão de fronteira: a interface de linha de comando e o leitor de CSV ficam fora das regras de negócio.

Um registro enxuto costuma conter:

• Título, data e status — por exemplo, Aceito ou Substituído.
• Contexto — problema, requisito e restrições que motivaram a escolha.
• Alternativas consideradas — opções viáveis comparadas pelos critérios do projeto.
• Decisão — a escolha feita e seu limite.
• Consequências — benefícios, custos e riscos aceitos.

Se a decisão mudar, preserve o ADR anterior e altere seu status para Substituído por ADR-00X, explicando brevemente a razão. Não reescreva o passado como se a escolha anterior nunca tivesse existido.

Uma nota de desempenho precisa permitir que outra pessoa entenda o que foi comparado e até onde a conclusão vale. Registre: versão ou artefato, carga de trabalho, máquina e sistema, versão do Python, configuração de concorrência, procedimento e fronteira medida.

A fronteira é especialmente importante: informe se o tempo inclui leitura, criação de processos ou threads, processamento, consumo dos resultados e gravação da saída. Compare execuções que realizam o mesmo trabalho e produzem resultado equivalente.

Use este mapa como checklist para a seção de desempenho ou para uma decisão registrada.

Use rótulos claros na redação:

• Fato medido: “Nas cinco execuções descritas, a mediana foi 1,82 s.”
• Expectativa: “Esperamos que a opção sequencial continue adequada para arquivos semelhantes.”
• Garantia não oferecida: “Não garantimos tempo máximo nem vantagem em máquinas ou cargas não avaliadas.”

A decisão pode apontar para um ADR quando ela afetar a arquitetura; não é necessário duplicar no README todos os detalhes do experimento.

Antes de fechar a entrega, transforme cada afirmação importante em uma trilha verificável: critério de aceitação → seção do documento → comando reproduzível → evidência observada.

A evidência deve identificar a versão e o artefato testado, por exemplo dist/resumo_csv-1.2.0-py3-none-any.whl. Executar a árvore de fontes, usar instalação editável ou importar módulos locais não substitui a verificação da distribuição empacotada.

Use uma tabela ou mapa simples para impedir que o README prometa algo que não foi conferido.

Confira no artefato validado os exemplos de ajuda, sucesso, configuração inválida e falha de acesso aos dados. Em cada transcrição, separe claramente o comando digitado, o conteúdo de stdout, o conteúdo de stderr, o código de saída e os efeitos em arquivos.

Uma transcrição didática marcada como simulada só ilustra formato: ela não é evidência da sua aplicação. Se a execução real divergir, registre a divergência e corrija o documento ou o comportamento, conforme o contrato aprovado.

Com sua wheel ou sdist validada, execute os comandos que você documentou em um ambiente limpo e fora da pasta do projeto. Use arquivos de entrada próprios, criando-os a partir do conteúdo textual descrito no README quando necessário.

Para cada cenário, anote: artefato e versão, comando, stdout, stderr, código de saída e arquivos criados ou preservados. Este tutorial não recebe arquivos nem verifica sua execução automaticamente; o objetivo é você confrontar o documento com o que observou localmente.