Pense em quem recebe
Uma entrega precisa funcionar para alguém que não acompanhou as conversas do projeto. Explique o objetivo, o que existe, como executar e como reconhecer o resultado esperado. Evite depender de frases como “é só fazer como antes”.
Escolha um projeto pequeno, como a central de pedidos, e prepare seu kit. O destinatário deve conseguir localizar os arquivos e entender as limitações sem ler um histórico inteiro. O README funciona como porta de entrada, não como depósito de todas as anotações.
Por que aprender
A qualidade da entrega determina o custo de continuidade. Uma ferramenta útil perde valor quando só seu autor sabe iniciar, testar ou atualizar.
✓ Fazer
Testar os passos do README em um contexto limpo.
✗ Evitar
Publicar todos os arquivos da pasta sem conferir.
Conceitos-chave
Organize o material por função
Separe código, exemplos, documentação e evidências. Use nomes descritivos e caminhos consistentes. Documentos de trabalho privados, credenciais e materiais que não pertencem à distribuição devem ficar fora do conjunto publicado.
Uma pasta de evidências pode conter o resultado dos testes e capturas de estados importantes. Não é necessário guardar todo arquivo temporário. Escolha o que demonstra o comportamento e explique como foi produzido, para que a conferência possa ser repetida.
Por que aprender
Organização por função reduz tempo de busca e evita misturar exemplos com dados reais. Ela também torna a revisão do conjunto a publicar mais simples.
Um caminho para aplicar
- Organize arquivos e escreva a porta de entrada.
- Execute as instruções com os exemplos fornecidos.
- Revise a distribuição e entregue contexto de continuidade.
Conceitos-chave
Escreva instruções executáveis
Liste pré-requisitos, comando de início e uma ação de teste. Execute exatamente as instruções em uma pasta limpa ou em um contexto equivalente. Se um passo depende de algo instalado globalmente, registre essa dependência.
Evite instruções que prometem uma automação inexistente. Se a tarefa exige uma decisão manual, explique o critério. O leitor deve saber o que esperar após cada etapa e como reconhecer um erro comum sem ter que adivinhar.
Por que aprender
Uma instrução só está validada quando foi seguida. Esse teste revela arquivos ausentes, dependências ocultas e nomes de caminhos que funcionam apenas no computador de quem escreveu.
projeto/
README.md
src/
exemplos/entrada.csv
docs/arquitetura.md
docs/decisoes.md
evidencias/verificacao.md
CHANGELOG.md
# Antes de publicar:
git status --short
git diff --cached --stat
Conceitos-chave
Monte uma base de conhecimento pequena
Escolha os documentos que explicam o projeto e registre assunto, versão e localização. Um índice de dez itens é suficiente para começar. A base pode alimentar um dossiê, mas precisa manter o vínculo entre resposta e documento.
Quando um arquivo mudar, revise os resumos que dependem dele. Uma base “viva” não significa gerar conteúdo sem parar; significa ter uma rotina de atualização com responsável, frequência e critério de mudança. Marque materiais desatualizados em vez de deixá-los competir com a versão atual.
Por que aprender
Uma base organizada preserva decisões e reduz perguntas repetidas. O controle de atualização impede que respostas antigas pareçam atuais só porque continuam fáceis de encontrar.
✓ Fazer
Manter exemplos fictícios separados de dados privados.
✗ Evitar
Documentar uma função que ainda não existe.
Conceitos-chave
Faça uma revisão de publicação
Antes de versionar, confira o conjunto exato de arquivos. Um ignore evita adicionar novos arquivos indesejados, mas não remove automaticamente os que já foram rastreados. Revise o status e o conteúdo preparado para o commit.
Depois de publicar, teste os links e os arquivos que devem abrir. Registre a versão entregue e os próximos passos. O resultado da publicação é um ponto de referência para manutenção, e não o fim da necessidade de verificar mudanças futuras.
Por que aprender
A revisão evita distribuir material privado ou uma versão incompleta. A identificação da entrega permite relacionar documentação, código e resultados de teste.
| Critério | Evidência esperada |
|---|---|
| Reprodução | Outra pessoa consegue executar o exemplo. |
| Coerência | README, mapa e código descrevem a mesma versão. |
| Continuidade | Limitações e próximo passo estão identificados. |
Conceitos-chave
Prática: entregue para um segundo leitor
Monte o kit da central de pedidos ou de outro projeto pequeno. Peça que uma pessoa siga o README, abra o diagrama, execute o exemplo e encontre uma limitação conhecida. Se estiver estudando sozinho, repita os passos em uma pasta nova.
Registre onde houve dúvida e ajuste a menor parte necessária. Ao final, escreva um resumo de continuidade com estado atual, decisões e próxima tarefa. O kit está completo quando permite usar e continuar o projeto sem depender da conversa que o criou.
Por que aprender
Esta prática encerra o curso conectando implementação e manutenção. Você passa de uma resposta produzida por IA para uma entrega que pode ser conferida, compartilhada e aprimorada.
Seu exercício
Prepare um kit com README, exemplo de entrada, saída esperada, mapa do fluxo e registro de verificação. Faça uma conferência dos arquivos que serão compartilhados.
Baixar ficha da práticaConferir resposta comentada
O README aponta para os demais documentos e contém passos testados. A entrada usa dados fictícios; a saída permite conferir as regras. O mapa corresponde ao fluxo implementado. A verificação informa resultado e limitações, e o próximo passo descreve uma única melhoria delimitada.
Cheque sua compreensão
Adicionar uma pasta ao .gitignore remove arquivos já rastreados?
Conceitos-chave
O que fica deste módulo
Um kit de entrega com instruções, mapa, evidências e próximos passos.
- ✓ Outra pessoa consegue executar o exemplo.
- ✓ README, mapa e código descrevem a mesma versão.
- ✓ Limitações e próximo passo estão identificados.
O progresso registra sua leitura. A prática fica concluída quando você confere a entrega.