Documentação Leve

Documente o mínimo possível.

O propósito de você documentar é comunicar o que você fez (ou o que precisa ser feito) para alguém distante temporal ou fisicamente.

Documentação é uma das formas de se levar ao Entendimento, mas o foco deve ser o Entendimento.

Documentação é apenas um meio e, em boa parte dos casos, não é o mais eficiente.

O que importa é o Entendimento, não o documento.

É importante evitar o padrão recorrente de só se comunicar por documentos. O analista manda um .doc para o cliente que aprova (sem ler). O desenvolvedor recebe o documento e, apesar de ver erros, fica calado e faz o que está escrito. Isso é péssimo e deve ser evitado.

Comunicando a parte técnica

No caso de gente nova na equipe, crie um workshop mostrando a motivação do sistema e percorrendo as telas, se for o caso. Isso dá o contexto geral.

Também é importante mostrar a arquitetura do sistema, uma visão de alto nível.

Ler código não é a melhor forma de comunicar a arquitetura.

Usar UML, nesse caso, é uma boa. Você pode se basear no modelo 4+1 de visão arquitetural, mas usar de maneira mais leve:

  • Modelo de domínio – com as entidades importantes em termos de negócio e os relacionamentos entre elas
  • Diagrama de componentes – mostrando os principais pacotes em que o sistema está organizado
  • Diagrama de implantação – mostrando como é implantado fisicamente o sistema quando em produção

Mas é importante que estes documentos estejam atualizados. Se não estiverem, utilize a oportunidade para atualizá-los.

Comunicando com o cliente

Para novos clientes, fazer um workshop e demonstrar o sistema e casos de sucesso parece algo bem profissional e, de certa forma, um marketing ativo.

É interessante ter manuais do usuário com telas e informações relevantes, além de um FAQ. Talvez, a melhor forma de publicar essa documentação é em um site ou wiki.

É importante focar nas funcionalidades mais complexas. Não há a necessidade de colocar funcionalidades básicas nos manuais.

Dica: se o seu software precisar de muitos manuais e FAQs, pode ser que ele precise de um investimento em usabilidade.

Também pode ser interessante fazer vídeos que demonstram como utilizar as funcionalidades mais avançadas.

Para ler
Alguns pensamentos sobre “documentação ágil”, do Guilherme Chapiewski

Anúncios