Seu time pergunta no chat como subir o projeto local, algo escrito em algum lugar. Você vê o sintoma antes de qualquer texto novo: ninguém encontra resposta porque o README virou manual de tudo.
Três tipos, três páginas
Daniele Procida separa tutorial, guia e referência no framework Diátaxis (Divio, 2017). Tutorial ensina com o leitor no comando, passo a passo. Guia resolve um problema de uma vez. Referência lista função, parâmetro e retorno. Você mantém as três em páginas distintas. Um README de 600 linhas misturando os três formatos é o motivo de ninguém achar a resposta.
Versionar junto com o código
Você guarda a documentação no repositório e muda a página no mesmo PR que altera o comportamento. Jared Bhatti e colegas defendem essa proximidade em Docs for Developers (Apress, 2021). Wiki separada envelhece em três meses porque ninguém lembra de atualizar.
Manter viva
Você coloca uma pergunta no checklist do code review: isso quebra documentação? Um link morto derruba o build. Andrew Hunt e David Thomas tratam do custo do código sem explicação em The Pragmatic Programmer (20th Anniversary Edition, 2019). Depois disso, o time consulta o documento antes de interromper alguém.
