Qual é uma maneira eficaz de registrar as razões por trás das decisões de design de produto?

Na nossa empresa, não usamos nenhum documento de design do produto. Temos três funcionários no total, portanto todas as discussões sobre design de produtos acontecem pessoalmente ou no Slack. (Também estamos no pacote básico do Slack, que permite apenas visualizar as mensagens mais recentes.)

Nosso produto ainda está nos estágios iniciais e, muitas vezes, revisitamos os elementos de design decididos há meses.

Um problema que enfrentamos com frequência angustiante é esquecer por que uma decisão de design de produto foi tomada. Isso resulta em horas desperdiçadas recauchutando o mesmo terreno.

Como podemos registrar efetivamente as razões por trás das decisões de design?

Nosso fluxo de trabalho é baseado no Pivotal Tracker. Uma solução que me ocorre é registrar as justificativas de todas as decisões relevantes de design como comentários sobre a história do usuário, mas isso não é confiável.

Para ser 100% claro: não estou falando sobre o design do código. Eu estou falando sobre o design do produto que é realizado pelo código. Em outras palavras, não estou falando de decisões como "devemos estruturar essa classe usando composição em vez de herança múltipla?"; Estou falando de decisões como "devemos exigir que um usuário confirme seu endereço de e-mail antes de poder fazer login?".

O objetivo da documentação é permitir que a empresa visualize um registro do motivo pelo qual as decisões foram tomadas, para ajudar na tomada de decisões adicionais sobre os mesmos tópicos.

Você registra as razões por trás das decisões de design, anotando-as. Idealmente próximo ao item que está sujeito à decisão (que não é uma "história do usuário" - as histórias do usuário são descrições do que deve ser implementado, não como).

É especialmente para isso que os comentários são feitos - para registrar por que uma parte específica de código ou estrutura se parece com ela (e não estou falando exclusivamente de comentários de código). Se o assunto do seu design for uma função, faça um comentário introdutório à função. Se for uma classe, faça um comentário no início de uma aula sobre a justificativa. Se você possui várias classes que devem seguir a mesma estrutura, adicione um documento de design separado (como um arquivo "leia-me") ao pacote que contém essas classes. Se o assunto do seu design for um diagrama UML, inclua comentários na seção de descrição do diagrama.

Os documentos de design do IMHO podem ter seu valor, mas se eles descrevem coisas muito "distantes" do item que descrevem, tendem a se tornar inconsistentes muito rapidamente. Portanto, minha recomendação é colocar qualquer documentação de design o mais próximo possível do item projetado.

Use documentos separados somente quando desejar documentar as decisões de design que afetam muitos locais diferentes do seu código de maneira transversal. Ao usá-los, tente torná-los parte de sua base de códigos e coloque-os no nível de hierarquia correspondente do assunto projetado (portanto, se você tomar uma decisão de design para um módulo que consiste em muitos arquivos de código-fonte, coloque a descrição de design " dentro "desse módulo, mas não em um arquivo de classe, não em uma" descrição de nível superior "que seja válida para outros módulos e, definitivamente, não em um Wiki separado fora do seu SCCS. Se você deseja gravar algum produto de" alto nível " decisões de design amplas e, em seguida, um documento de nível superior talvez seja o melhor local, mas verifique se este documento permanece nesse nível de abstração.

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!

Eu sugiro configurar uma instância privada do MediaWiki ou algum software wiki semelhante. É realmente fácil organizar e reorganizar o conteúdo lá, e você pode copiar e colar novas discussões diretamente na guia Discussão dos artigos relevantes da wiki. Usamos o MediaWiki no meu último trabalho para todos os nossos documentos de arquitetura e API, e foi um salva-vidas.

Pense nisso do ponto de vista do codificador que será solicitado a alterá-lo em 12 meses.

Se você adicionar esta regra de negócios como um teste automatizado, a alteração será feita E ENTÃO você obterá do requisito contraditório o requisito contraditório (e esperamos capturar a pessoa associada ao requisito original e o motivo para especificá-lo).

Considero o documento de design (o local em que você coloca seus diagramas BPMN, diagramas de transação e até uma foto do quadro branco etc.) como semelhante ao código, apenas um formulário não executável ... o que significa que você está tentando O registro é semelhante a um comentário de código, mas um requisito (testável) especificado antecipadamente no design. Presumivelmente, se você é uma loja ágil, ainda projeta seu código, basta fazê-lo no último minuto antes de escrevê-lo. Mantenha isso na base de código com todos os outros documentos do projeto.

Faça o que fizer, verifique se ele é armazenado de maneira pesquisável (por exemplo, convém abrir todas as regras de negócios relacionadas à "autenticação" ao especificar novas alterações.

Como sempre, quando você escreve algo, precisa se perguntar quem é o público-alvo. Eu acredito firmemente que os documentos de design existem para meus desenvolvedores pares, atuais ou futuros. O documento os ajuda a entender o que estou construindo ou o que foi construído (visão geral de alto nível) e, mais importante, o porquê. É um lugar para documentar as alternativas que você considerou, os prós e os contras de cada uma.

Dizer que não há problema em algum projeto viver no cérebro das pessoas deixa de fora que os desenvolvedores seguem em frente e encontram trabalhos diferentes, levando consigo essas informações valiosas.

Ter o seu código como a única documentação de design é como percorrer a cidade usando uma lupa. Um mapa é muito mais útil (infelizmente não existe um equivalente de GPS para o código-fonte).

Concordo que a documentação do projeto apodrece ainda mais rápido que o código. E como não há validação possível entre os dois, a única coisa que você pode fazer é mantê-los juntos. IMO, um documento de design datado ainda fornece informações valiosas.