Olá Elías

No sistema da alura e no interno da caelum usamos em especial os testes de unidade como base para saber o que faz cada metodo. Apesar de eu não gostar muito da frase que diz que o teste é a documentação, acredito sim que se encaixa em muitos cenários.

Para integrações, situações mais complicadas e susbsistemas nós temos arquivos markdown comitados diretamente nos repositórios do github.

Olá Paulo,

Obrigado pelo retorno!

Sobre os arquivos markdown:

• Eles são gerados manualmente, automaticamente ou um pouco dos dois?

• Quem gera esses arquivos (próprio desenvolvedor, testador, etc)?

• Como vocês fazem para manter esta documentação atualizada, existe um procedimento automático (e-mail, etc) ou manual (lembrete no monitor)?

Sim, são feitos manualmente.

O proprio desenvolvedor, que aqui ele mesmo faz os testes.

Infelizmente nao temos procedimento para lembrar de atualizar. Mas como essa documentacao costuma ser extra para auxiliar pontos mais complicados (como setup do projeto), muitas vezes sao feitos e refeitos, entao todo mundo passar por aquele documento e o revisa. Lembrando que automatizamos ao maximo o deploy e setup do projeto na propria maquina, entao esses documentos acabam sendo bem curtos.