Na faculdade me pediam muita documentacao mesmo, mas na vida real a documentacao sempre fica desatualizada. A melhor forma que encontrei de documentar meus softwares foi escrevendo testes. Em cada teste eu descrevo o motivo daquele teste existir e oq ele deve testar. Quando alguem quer entender oq uma classe faz ela pode ler os testes. A unica coisa que eu documento sao os passos para executar o programa, onde estao as classes mais importantes e os comandos basicos.