Uma das coisas com melhor relação custo/benefício que provavelmente pode haver num projeto é uma Wiki, uma boa Wiki. Qualquer equipa, independentemente da área de negócio, da senioridade dos membros ou das tecnologias com que trabalha pode ter uma e tirar mais proveito dela do que o pouco trabalho que dá criá-la e mantê-la, tendo só que ter em atenção alguns (poucos) pormenores.

O erro mais comum, e também mais fácil de evitar, é cair no exagero de querer documentar tudo, ou então tenta manter uma estrutura super rígida dos documentos ou dos formatos do texto. Quanto mais simples, melhor. Idealmente deve ser só um conjunto de ficheiros flat (nada de pastas dentro de pastas dentro de categorias dentro de …) com algumas hiperligações entre eles. Um excelente exemplo de tudo isto que falei é a Wiki do Scoop, onde qualquer pessoa encontra facilmente o que quer, seja começar rapidamente a usar a ferramente ou perceber melhor do que se trata.

Fora isso é só ter algum cuidado para que seja acessível por todos os stakeholders, porque apesar de realisticamente ser pouco provável que alguém fora das equipas técnicas a vá consultar, não deixa de ter utilidade interna. No pior dos casos obriga a pessoa que está a escrever a ter uma boa ideia do que está a falar, o que obriga a falar com várias pessoas até ter uma ideia global minimamente clara do projeto, o que acaba por ajudar a construir uma visão clara e partilhada pela equipa. Podia fazer tudo isto só com algumas conversas e evitar a perda de tempo que parece ser escrever tudo? Talvez, mas:

Ainda que não vejam utilidade em tudo isto, espero pelo menos conseguir convencer alguém de que uma versão light de uma Wiki vale a pena: um glossário do projeto. Isto não é mais do que um nome feio para uma coisa bastante simples: uma lista com o vocabulário relacionado com o projeto, que pode conter coisas como termos de negócio (do género omnichannel, wholesale, etc) ou nomes de produtos e projetos (por exemplo: donald é um dashboard de vendas, palin um agregador de newsfeeds, …).

Quando li isto pela primeira vez no The Pragmatic Programmer achava que era só mais uma ideia engraçada para quando se tivesse pouco tempo livre, mas a minha pouca experiência tem mostrado que ter um vocabulário partilhado entre a equipa tem um valor enorme, e para chegar a um entendimento comum conversas laterais não chegam. Qual é a diferença entre client e customer? O que é instore? Vouchers, promocodes e gift cards são a mesma coisa? Tudo isto é fácil de responder com um glossário, e evita-se o problema de ter vários nomes para a mesma coisa, ou ainda pior, o mesmo nome para várias coisas.