Uma documentação bem feita é como uma rodovia recapeada: não há nada para atrapalhar o progresso. Por outro lado, fazer um software e não documentá-lo é como dirigir um carro com os olhos vendados, numa avenida esburacada, durante uma manifestação pública. O futuro não vai ser bem-vindo.

Documentação costuma ser o patinho feio da informática, tanto para programadores quanto para usuários. O programador sempre acha que o código está óbvio e perfeito, e o usuário, que instruções são desnecessárias: tem mouse, é só clicar.

Há dois tipos de documentação:

  • a que vai ser lida pelo desenvolvedor, para refatorar, fazer manutenção ou dar continuidade ao projeto, e é normalmente escrita junto com o código ou compilada com geradores de docs
  • a que vai ser lida pelo usuário (chamada de "help" ou ajuda), e pode ser lida separadamente ou em conjunto com a tela ativa.

Quando documentamos projetos de software, não só estamos preservando o sistema contra imprevistos, como aproveitamos para fazer uma checagem: será que o código está fazendo o que deveria? E quando o usuário segue as instruções, ele também faz uma checagem: será que o que ele está usando é o que foi pedido?