Considere uma abordagem ágil. Quero dizer, se você tem os recursos de tempo e excelentes habilidades de escrita para anotar todas as decisões de design que tomam junto com suas razões, basta documentar tudo. Realisticamente falando, suponho que você não esteja nessa posição. Uma abordagem ágil pode ajudar com um desafio fundamental para a documentação das justificativas: muitas vezes você não sabe quais são as mais importantes até mais tarde.
Vamos abordar o problema de um ponto de vista holístico. Vocês têm justificativas para a sua decisão. Eles estão presos em squishyware agora, o cérebro da equipe. Apesar da quantidade de documentação de crédito recebida, o armazenamento de justificativas no sqishyware não é tão ruim assim. Na verdade, somos realmente bons como espécie em lembrar as coisas importantes. É por isso que toda grande corporação possui "conhecimento tribal", mesmo quando essas empresas buscam documentar todo esse conhecimento tribal.
Agora você tem um problema. Você está descobrindo que o sqiushyware não está mantendo as justificativas suficientemente boas. É bom para você perceber que há um problema e identificar que ele precisa ser resolvido! Nem sempre é um passo fácil! Portanto, temos certeza de que a solução é descarregar parte dessa justificativa na documentação. No entanto, isso não é suficiente. Nunca podemos esquecer a segunda metade do quebra-cabeça, que é recarregar a justificativa no squishyware quando você precisa tomar uma decisão. Eu já vi muitas equipes que documentam tudo como uma loucura, mas o conteúdo não é realmente organizado para ajudar a tomar boas decisões, então elas acabam esquecendo as razões, mesmo sendo anotadas .
Então você tem um processo de duas etapas. Você precisa obter a justificativa do squishyware e da documentação. Então você precisa garantir que a documentação esteja organizada o suficiente para trazer o racional de volta ao squishyware quando você precisar! Agora, acho que temos uma declaração de problema suficiente para perceber onde os desafios serão agradáveis. Quando você está documentando, normalmente não sabe quem irá vê-lo mais tarde ou o que eles estão procurando. Da mesma forma, quando você olha para a documentação, normalmente não sabe o que está procurando (na melhor das hipóteses você pode saber quando).
Portanto, uma grande empresa pode tentar lidar com isso em dois grandes blocos. Primeiro, eles podem desenvolver requisitos com base no que as pessoas precisam quando pesquisam a documentação. Em seguida, eles usam esses requisitos para criar um processo para desenvolver a referida documentação. E, se me atrevo a dizer, todos reclamam porque quase ninguém sabe exatamente como deve ser a documentação no primeiro dia. A documentação está sempre incompleta e os desenvolvedores estão sempre reclamando que o processo é muito oneroso.
Hora de ir ágil.
Meu conselho seria iniciar um esforço ágil para melhorar seu processo de documentação: os nove metros inteiros do squishyware ao documento e de volta ao squishyware. Reconheça antecipadamente que você perderá algumas informações porque seu processo não é perfeito, mas tudo bem, porque você ainda está tentando descobrir o processo! Você perderia mais se tentasse criar uma solução única para todos.
Alguns petiscos em particular: - Explore a documentação informal. A documentação formal é ótima, mas consome muito tempo. Um dos objetivos da documentação é liberar informações do squishyware do desenvolvedor e colocá-las no papel. A documentação informal reduz ao mínimo o custo de fazê-lo.
- Aceite formatos de documentação não confiáveis. Nada vai dar certo na primeira vez. É melhor obter os dados e descobrir como torná-los confiáveis mais tarde. Por exemplo, você pode documentar suas razões em um bloco <rationale> </rationale> ou algo semelhante, o que facilitaria a coleta desses dados posteriormente. Armazenar as justificativas em uma história de usuário, por enquanto, está ótimo!
- Nunca esqueça o valor da organização. Descubra como você, em equipe, gosta de procurar razões na documentação e tente documentar isso. Cada equipe terá um processo diferente. Em uma das minhas equipes, nunca conseguimos encontrar o ticket com a justificativa imediata. O que poderíamos fazer é encontrar uma linha de código que importasse, fazer um
svn blamepara descobrir quando ela mudou e por quê, e depois procurar os bilhetes. Quando estávamos lá, normalmente colocamos toda a justificativa necessária na passagem. Isso funcionou para nós, descubra o que funciona para você.
- A documentação orgânica pode crescer com o tempo. É raro os desenvolvedores saberem quais são as razões mais importantes no dia em que precisaram escrevê-las. Geralmente descobrimos quais eram importantes mais tarde. Se você tiver um processo de preparação para a documentação que permita que os desenvolvedores gerenciem seu próprio pequeno jardim de justificativas, os importantes surgirão à tona. Ainda mais importante, as razões podem mudar. Você pode perceber que duas mudanças diferentes, com duas justificativas diferentes, foram realmente melhor descritas por uma única justificativa que funciona para ambas. Agora há menos conteúdo entre você e as decisões!