Um documento de design deve conter uma discussão dos prós / contras de um determinado design ou deve se concentrar em fatos e justificativas?

Atualmente, estou no processo de atualizar um documento de design para que esteja correto e atualizado para futuros desenvolvedores.

Atualmente, o documento concentra-se apenas nos fatos, apresentando como é o design. Não há justificativa para nenhuma decisão apresentada. Acredito que é importante capturar a lógica para que os desenvolvedores saibam por que algo é do jeito que é, pois isso provavelmente afetará decisões futuras. Não é possível adicionar justificativa para todas as decisões de design, especialmente aquelas tomadas antes de eu começar a trabalhar no projeto, mas estou fazendo o que posso neste departamento.

No entanto, algumas das decisões de design são, respeitosamente, muito ruins, dados os requisitos do projeto. Existem alguns bons, também.

Meu pensamento inicial era que eu deveria incluir uma discussão sobre problemas de design e possíveis soluções ou soluções alternativas para esses problemas, para focalizar a atenção de futuros mantenedores, mas não tenho certeza se o documento de design é um local para esse tipo de discussão e informações. Não quero que uma "crítica" de design seja usada como "rasgando um novo design", pois outras pessoas trabalham nesse sistema e atualizam o documento, pois isso é claramente inapropriado.

Meu gerente apoiaria qualquer decisão, então depende de mim. Independentemente da abordagem adotada, o documento produzido seria oficialmente versionado e fornecido aos desenvolvedores que trabalham no sistema, normalmente antes de serem encarregados do trabalho de desenvolvimento. Espera-se que um novo desenvolvedor se familiarize com os documentos associados a um determinado sistema de software antes de iniciar o trabalho de desenvolvimento.

Questões:

• Se um documento de design se apegar a fatos brutos ("este é o design") e a justificativa ("aqui está o porquê desse design") ou também deve ser usado para apontar problemas não defeituosos no design que possam ser problemáticos para o design futuros desenvolvedores?
• Se o documento de design não deve ser usado para capturar essas informações, que tipo de documento deve capturá-lo e o que mais deve ser capturado com uma discussão sobre as razões do design, as compensações e os problemas conhecidos (que não são defeitos, pois os defeitos são rastreados) usando outras ferramentas)?

Se os prós e os contras puderem ser resumidos em uma ou duas frases, não há problema em colocá-los em um documento de design. Qualquer coisa a mais deve ser separada.

Onde trabalho atualmente, geralmente há um documento separado "Decisões de design" para rastrear todas as decisões grandes e importantes. Geralmente formatado com um parágrafo que descreve o problema (como "Alguns arquivos precisam ser movidos de um servidor para determinados usuários no final de cada ciclo de processamento, existem várias maneiras de fazer isso ..."), uma tabela com colunas " descrição da solução "(como" mover arquivos via FTP ")," profissionais "(como" Fácil de gerenciar pelos usuários ")," contras "(como" não seguro o suficiente para conformidade com ABC-XYZ ") e uma conclusão de que explica por que uma decisão específica foi escolhida (como "O FTP não será usado porque não poderá atender a certos requisitos de conformidade"). O documento de design geralmente faz referência apenas à decisão escolhida,

Se um documento de design se apegar a fatos brutos ("este é o design") e a justificativa ("aqui está o porquê desse design") ou também deve ser usado para apontar problemas não defeituosos no design que possam ser problemáticos para o design futuros desenvolvedores?

Não é "um ou outro".

Ninguém lê a documentação em primeiro lugar. Eles roçam - na melhor das hipóteses. Portanto, escreva o menor número possível de documentos. Um documento é tudo o que alguém tem paciência. É improvável que um segundo documento "não-desgin" com "outros problemas" seja lido.

Vantagens de um documento? As pessoas podem ler.

Desvantagens de um documento? Poucos. Principalmente fica desatualizado.

Vantagens de vários documentos? Nenhum.

Desvantagens de vários documentos? Leia o princípio DRY e programação alfabetizada. Múltiplos documentos significa múltiplas fontes de erros. Cada documento discorda do outro e discorda do código. Isso é bastante óbvio. Este é o caminho da loucura.

Evite torcer a mão.

Um documento de prós e contras pode arrastar-se para profundidades indefinidas de discussões incômodas e atraentes.

Se você acha que é necessário apresentar prós e contras, mantenha-o curto e direto ao ponto.

Concentre-se no que é.

Mantenha o que não se resume aos ossos.

Se você fez benchmarks, estudos ou realmente explorou alternativas, documente isso. Mas se você está apenas pensando em alternativas, minimize-o.

Esta não deve ser sua história pessoal de provações e tribulações.

• Teve algum problema? Consertou? Levou semanas? Realmente lutou? Quase uma anedota interessante. Está consertado no código. As versões anteriores, versões erradas, versões de buggy e versões de baixo desempenho não importam. Na melhor das hipóteses, são blogs.

• Ainda tem algum problema? Não consertado? Isso significa que existem alternativas. Documente isso.

Existem três fatos importantes no processo de tomada de decisão:

• O que foi tentado e não funcionou (e por que não funcionou, porque você está segmentando um alvo em movimento)
• O que é
• O que poderia ser (apenas aguardando a implementação do X ...)

No entanto, além de "O que é", todos os outros irão confundir o leitor e impedir que ele afunde o sistema.

Eu gosto da idéia de capturar os outros 2, embora sejam menos interessantes para aprender o sistema, eles podem economizar tempo ao alterá-lo.

Portanto, aproveitaria a ideia exposta ao @FrustratedWithFormsDesigner, com um toque especial. Em vez de criar outro documento, com um ciclo de vida próprio, eu acrescentaria uma seção em anexo. Então, para cada decisão digna de discussão, eu apontaria para a entrada relevante no anexo.

Sim. Um documento de design deve explicar os benefícios, riscos e suposições associados ao design que está sendo descrito. Um documento de design tem vários propósitos:

1. Escreva o design para que todos o entendam e para que o entendimento de cada pessoa não seja desviado com o tempo.

2. Comunique o design a pessoas não técnicas que trabalham no projeto.

3. Auxiliar no agendamento, alocação de recursos, estimativa de custos e outros tipos de planejamento.

4. Torna-se uma parte importante da documentação geral do projeto. Quando você ingressa em um projeto em andamento ou precisa manter um projeto concluído, a vida fica muito mais fácil se houver um documento de design bem escrito.

5. Geralmente é um dos resultados exigidos por contrato.

(Provavelmente existem outros, mas estes são um bom começo.)

Cada um desses objetivos é bem atendido por um documento de design que explica claramente por que esse design foi escolhido e quais são os riscos associados:

1. É essencial que todos na equipe saibam quais são os riscos e benefícios para que possam trabalhar juntos para evitar esses riscos e fazer o melhor uso dos benefícios do design.

2. Para os membros não técnicos da equipe, entender os riscos e os benefícios geralmente é mais importante do que os detalhes do próprio design.

3. O gerenciamento de riscos é uma das coisas mais importantes que um gerente de projetos pode fazer para garantir o sucesso, e o primeiro passo é identificar os riscos que precisam ser gerenciados. Cabe ao gerente decidir como lidar com os riscos, mas é responsabilidade do designer apontar riscos conhecidos do design.

4. Mesmo quando um risco não é mais um problema, geralmente é útil documentá-lo, pois pode ajudar a explicar a situação no momento em que o design foi criado. Isso pode permitir que um mantenedor decida algo como: "Ok, eles fizeram dessa maneira naquela época porque ... mas isso não é mais um problema, então eu posso substituir esse código por uma implementação mais simples e rápida". O mesmo vale para os benefícios, é claro.

5. Se você estiver trabalhando em um projeto para um cliente, é particularmente importante documentar riscos e benefícios. Isso avisa o cliente de que as coisas podem dar errado em determinadas circunstâncias ou que solicitar alterações no design pode comprometer alguns dos benefícios prometidos.

Entendo que você está trabalhando com um documento de design existente para um sistema que já foi implementado. Nesse caso, muitos dos riscos possíveis não são mais riscos, portanto, não faz muito sentido tentar documentá-los após o fato. No entanto, agora você tem a vantagem da retrospectiva, pois pode ver as partes do design original que não funcionaram tão bem. Eu acho que você deveria: adicionar uma seção separada que identifique as áreas problemáticas atuais e proponha soluções (incluindo riscos associados!); ou crie um documento separado que faça a mesma coisa. Esta nova seção / documento pode evoluir para o documento de design da próxima versão do software.

Aqui está uma entrada de blog sobre como escrever documentos de design que você pode achar útil.

Se houver razões válidas para evitar soluções mais óbvias ou padrão, essas devem ser observadas. Você economizará a muitos problemas. No entanto, uma tecnologia específica pode melhorar com o tempo, portanto, seus motivos podem não ser aplicáveis. Um futuro desenvolvedor pode usar seu próprio julgamento.

Não sei se há muitos benefícios em apontar todas as deficiências. Pode não ser prático fazer as alterações ou outras prioridades ocorrerão. Você pode corrigir alguns deles em um futuro próximo e isso será apenas mais uma coisa a ser atualizada.

Eu pessoalmente não o colocaria no documento de design. Um documento de design deve descrever como é, não o porquê.

Se você acha que há uma boa necessidade de uma história por trás do motivo, o design é o que é, talvez você deva colocar isso em um artigo da wiki (ou em qualquer base de conhecimento que sua empresa use) para que possa haver um histórico do evolução do design. As pessoas podem ler, editar e adicionar sugestões. Dessa forma, é mais uma discussão aberta do que uma sobrancelha batendo em um documento.

Concordo com você em colocar a justificativa no documento de design.

De qualquer forma,

no processo de atualização de um documento de design escrito por outra pessoa, permaneceria humilde e não tentaria adivinhar por que essa decisão foi tomada.

Então,

Inseriria justificativa apenas sobre as alterações feitas no design durante a manutenção.