Criar documentos como parte do Agile

No meu local de trabalho, enfrentamos um desafio em que "ágil" com muita frequência significa "requisitos vagos, critérios de aceitação ruins, boa sorte!" Estamos tentando resolver isso, como um esforço geral de melhoria.

Portanto, como parte disso, proponho que geremos documentos de design que, acima e além do nível da história do usuário, reflitam com precisão o resultado de investigações preliminares do efeito de um determinado recurso no sistema e incluam respostas às perguntas que temos perguntou o negócio.

Existe um padrão eficaz para isso?

Atualmente, enfrentamos uma situação em que um novo recurso pode impactar várias áreas em nosso sistema "grande bola de lama" , e as estimativas estão começando a subir devido a essa dívida técnica. Esperançosamente, processos de design mais criteriosos podem ajudar.

"requisitos vagos, critérios de aceitação ruins, boa sorte!"

Sim, este é o mesmo tipo de requisitos que você obtém, mesmo que tente prendê-los também! (por exemplo, um documento de 10.000 requisitos que levou um cliente do governo 4 anos para ser criado ainda estava cheio de inconsistências, imprecisões e até declarações contraditórias internamente. Se 4 anos de documentação de requisitos não podem fornecer um requisito decente e exato, faça você já pensou que conseguiria algo não vago?)

Então ... a maneira ágil foi inventada para entender que isso acontece e trabalhar com ela em vez de tentar trabalhar contra ela.

Você começa perguntando "o que você quer" e o cliente responde com "algo assim". Você trabalha e depois volta para o cliente e diz "é assim que você queria?", E o cliente geralmente diz "sim, mas ..." e depois pergunta "o que você quer".

Eventualmente, você consegue exatamente o que o cliente queria, mesmo que ele não saiba o que é isso! (inferno, eles nunca sabem o que querem, não exatamente).

Em nossa equipe, desde que agilizamos, também tentamos restringir e entender a quantidade de documentação realmente necessária. Posso compartilhar com você o que aprendemos até agora.

Antes de mais nada, leia este artigo na documentação do Agile / Lean . Muito boa leitura.

Em segundo lugar, eu recomendo fortemente que você reconsidere a produção de documentos de design após o trabalho preliminar de histórias. Já tentamos isso antes e provou ser um desperdício. No meio da última versão, decidimos atualizar os documentos de design SOMENTE APÓS o código da história ser entregue. E agora estou pensando que isso é muito cedo.

Você precisa se perguntar por que deseja criar documentos de design antes da codificação. Para nós, estas foram as razões:

1. Como equipe, precisamos entender como a história afetará o design.
2. Ter documentos de design mostrou-se útil quando novos membros (ou temporários) se juntam à equipe ou quando retornam ao código em que ninguém trabalha há mais de um ano. Portanto, eles são úteis para a memória organizacional para ajudar a entender como o código funciona.
3. Os documentos de design são úteis para engenheiros de manutenção que podem precisar solucionar problemas do código após o lançamento.

Para satisfazer (1), você não precisa produzir um documento de design real. Sua equipe ainda deve ter uma fase de design antes da codificação, mas essa fase pode ser tão simples quanto uma sessão de 15 minutos na frente de um quadro branco ou de um guardanapo. Você não precisa produzir um documento real que levará horas (se não dias) para escrever apenas para discutir as alterações de design.

(2) ou (3) não são necessários durante o desenvolvimento da história atual e, mais do que provavelmente, não serão necessários para várias iterações subsequentes.

Lembre-se também de que toda vez que um membro da equipe estiver escrevendo / atualizando documentos de design, esse é o momento em que o código não está sendo gravado. Quando você escreve documentos antes do código real, há quase 100% de chances de que eles precisem ser atualizados porque, assim que você começa a codificar, o design sempre acaba sendo alterado. E mesmo se você escrever documentos de design após o código, como nossa equipe aprendeu, a refatoração de histórias subsequentes ainda altera o design.

Então, o que eu recomendaria:

1. Inicialmente, produza projetos / modelos temporários o suficiente para que sua equipe possa ter uma conversa inteligente antes da codificação. Não espere mantê-las e não perca tempo formalizando-as.
2. Produza apenas a documentação oficial do projeto se alguém precisar (por exemplo, sua equipe tem uma necessidade real de memória organizacional)
3. Produza apenas a documentação do projeto no código que foi estabilizado. Não faz sentido tentar documentar um módulo que continua sendo alterado a cada iteração.
4. Produza documentos de design que descrevam completamente um módulo (ou parte do produto). No passado, costumávamos escrever documentos de design que documentavam as alterações que precisavam ser feitas. Esses documentos eram completamente inúteis assim que o lançamento foi feito.
5. Mantenha o documento em alto nível. Se você escrever 20 páginas cobrindo arquitetura e design de alto nível, esse documento a) será realmente lido por outras pessoas eb) ajudará as pessoas a se familiarizarem com o layout geral do seu código. Para detalhes, as pessoas podem ir direto ao código. Se você escrever 700 páginas de especificação detalhada, elas quase sempre não corresponderão à realidade, é demais para alguém ler e você terá que manter e atualizar 700 páginas em vez de 20 sempre que alterações futuras forem feitas.

O "mantra" ágil não deve ficar inteiramente sem documentação.

O mantra do Agile é preferir " Software de trabalho em vez de documentação abrangente ". Mas observe a parte na parte inferior do manifesto.

Ou seja, enquanto houver valor nos itens à direita , valorizamos mais os itens à esquerda ".

O tio Bob tem uma boa política para documentação

Não produza nenhum documento, a menos que sua necessidade seja imediata e significativa .

Você está certo que algumas pessoas usam o Agile como desculpa para não produzir documentação, mas isso é ruim. Está ignorando os bits que destaquei nas citações acima.

Tudo o que foi dito, quando você diz 'atualmente enfrentamos uma situação em que um novo recurso pode impactar várias áreas em nosso sistema "grande bola de lama"', se você for Agile, precisará fazer algo sobre isso.

Quando você tiver sua documentação, use-a para modularizar seu código. Dessa forma, você remove a necessidade de longo prazo de manter a documentação (o que não acontecerá), removendo a necessidade de longo prazo da documentação.

ie Torne a necessidade imediata e significativa.

A questão do ágil é que os esforços de documentação realmente precisam ser conduzidos pela equipe de scrum. Se os desenvolvedores não acharem que a documentação externa seja suficiente para suas necessidades, a história do usuário será bloqueada até que ocorram. Se a empresa achar que os desenvolvedores não estão produzindo documentação adequada, o proprietário do produto insiste em fazer parte dos critérios de aceitação. Por causa disso, achei nossa documentação mais focada e eficaz desde que passei para o scrum.

Usamos o VersionOne para rastrear nossas histórias de usuários, mas tenho certeza de que nossos métodos se aplicam a outros sistemas. Permite anexar arquivos a histórias de usuários. Descobrimos que esse é um local extremamente útil para colocar documentos de design.

Por um exemplo que funcionou muito bem para nós, tivemos a necessidade de testar um novo design de placa de circuito o mais rápido possível após a construção do protótipo. Criamos duas histórias de usuário para tudo o que era necessário testar: uma para projetar o teste e outra para executá-lo. Um critério de aceitação para a história de design foi que o procedimento de teste foi totalmente documentado na história de execução.

Quando chegamos à parte dos testes, tudo correu mais bem do que eu já vi. Acabamos de abrir a história do usuário e seguimos o procedimento passo a passo. A documentação era exatamente o que precisávamos para completar a história, nem mais nem menos.

Temos outra história em nosso backlog apenas para melhorar a documentação de um chip que usamos, a fim de tornar mais fácil para outras equipes buscá-lo em seus próprios produtos.

Em resumo, se você sentir que sua documentação está sofrendo, a solução é tão fácil quanto criar uma história de usuário separada para ela e / ou fazer parte dos critérios de aceitação.

Quando você fala de requisitos insuficientes, a primeira coisa que me vem à mente é garantir que você tenha os critérios de teste. Se possível, crie alguns casos de teste automatizados reutilizáveis ​​para partes existentes do sistema. Quando todos se sentirem confortáveis ​​com isso, passe a escrever os casos de teste antes que o código seja escrito. Bons casos de teste podem fazer muito para documentar os comportamentos de um sistema.

Quanto aos documentos de design específicos a serem usados, como já foi dito, isso depende muito das necessidades da equipe e da próxima tarefa que eles estarão realizando. Quando possível, tente usar ferramentas que podem gerar os documentos (do código) que você usaria ou gerar o código do documento. A manutenção da documentação pode se tornar bastante cara, portanto, escolha com sabedoria quando você persistir em um documento de design.

Pessoalmente, tive bom sucesso com diagramas de classes gerados a partir de casos de teste de código e adequação. A equipe imprime alguns diagramas da turma, faz uma sessão de marcação com o proprietário do produto e depois formula uma estimativa a partir daí. No que diz respeito à fitnesse, tenho a sorte de trabalhar com dois proprietários de produtos que são muito bons em expressar o que desejam em planilhas, que são convertidas em tabelas para fitnesse.