Criar documentos como parte do Agile

25

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.

asthasr
fonte
4
A solução da Agile para isso é a comunicação. Pessoas responsáveis ​​por saber o QUE devem estar sempre acessíveis aos desenvolvedores para consultas. Além disso, você deve ter testes de unidade e refatoração frequente para manter a "grande bola de lama" sob controle.
Euphoric
3
Eu sei que devemos ter essas coisas. Nós não. Estou tentando nos ajudar a chegar lá, e estou tentando instituir uma estrutura confiável e repetível para as comunicações ( afinal, documentos são comunicação). O problema é que, agora, entramos em um pesado "faça já!" ciclos, e contamos com a comunicação ad hoc que resulta em pessoas com silos de conhecimento, porque não há referência para informações reais sobre um recurso que surge após a história do usuário.
Asthasr
4
O Agile não é contra a documentação - é contra a documentação inútil. Escreva a documentação necessária e não mais. Especificamente, lembre-se de que a documentação é apenas uma referência ao modelo mental que você (a equipe) tem em suas cabeças. O último é o material realmente importante - no entanto, você nunca pode documentá-lo completamente. Em vez disso, mantenha-o sincronizado por meio de muita comunicação e anote apenas referências suficientes para garantir que o modelo seja mantido consistente a longo prazo.
Péter Török
Eu acho que você deveria fazer uma pergunta diferente desta. Para esse tipo de pergunta, você receberá "documentos genéricos quando OK", que não ajudarão muito. Você deve perguntar se a sua solução para o seu problema está correta e perguntar sobre outras soluções possíveis.
Euphoric
4
"O Agile não é contra a documentação - é contra a documentação inútil.": Todo processo de desenvolvimento é contra a documentação inútil (de acordo com sua definição de útil e inútil).
Giorgio

Respostas:

18

"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).

gbjbaanb
fonte
Essa anedota do documento de design do governo é interessante, existe uma fonte? Ou apenas algo que você experimentou em primeira mão?
precisa saber é o seguinte
@ user145400 algo que eu experimentei :-(
gbjbaanb
13

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.
DXM
fonte
O que você está dizendo parece semelhante ao que estou tentando chegar; temos uma bola de barro complexa e quero documentos simples que: a) comuniquem a intenção comercial de um recurso específico (ou seja, histórias de usuário elaboradas, com perguntas respondidas); b) apontar quais partes do código e as APIs existentes serão afetadas; ec) são tratados como artefatos únicos, não como algo que precisa ser atualizado a cada novo recurso, para sempre. Dizer que 20 páginas é "alto nível" é interessante para mim - somos desprovidos mesmo disso. :)
asthasr
@syrion: Com base no que você acabou de dizer, parece que você deseja documentar detalhadamente cada história e produzir um documento de "diferença de design" (ou seja, definir a diferença entre o que está no código hoje e o que estará no código quando o a história está terminada). Você tem uma audiência para esses documentos? Pela minha experiência, estou prevendo que ninguém realmente os lerá. Os desenvolvedores que trabalham na história de hoje já sabem o que precisa mudar (eles escreveram o documento ou fizeram parte da discussão inicial). E se você tentar capturar todos os detalhes das mudanças que você está prestes a fazer para uma história, ...
DXM
... você gastará mais tempo escrevendo documentação do que realmente codificando. E assim que a história terminar, como você disse, esses são artefatos únicos. Então, por que você precisa produzi-los em primeiro lugar?
DXM
porque no momento temos um ambiente repleto de silos de conhecimento. Temos pessoas que conhecem o subsistema A porque o escreveram e B porque ajudaram no suporte quando ele explodiu pela última vez, mas nunca tocaram em C e D foi reescrito desde então. É difícil para iniciantes e contratados externos entrar ou permanecer no circuito.
Asthasr
@syrion: realmente parece que você tem a mesma necessidade que nós. No entanto, fiquei perplexo quando você disse que queria documentos simples que ... eram tratados como artefatos únicos. Então, digamos que você tenha uma camada que converse com o banco de dados e 6 histórias que exijam alterações nessa camada. Você está planejando produzir 6 documentos diferentes, juntamente com cada história? Ou você deseja ter uma única especificação de design para a camada DB? No entanto, a especificação única é algo que precisará ser atualizado com todos os recursos que tocam na camada do banco de dados.
DXM
3

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.

pdr
fonte
Esta resposta é "correta", mas realmente não pensa além disso. Que tal um projeto de arquitetura, por exemplo? E quanto à rotatividade de desenvolvedores / negócios? Como isso é tratado por muitos testes de unidade de qualidade?
Paul
@Paul: É uma boa idéia ter diagramas de arquitetura de MUITO alto nível, junto com padrões de codificação muito leves, para os novatos. Descobri que uma boa maneira de manter esses documentos atualizados é mantê-los em um wiki e fazer com que cada novato atualize onde eles acham que está datado. Mas essa pergunta era sobre documentos de projeto iniciais especificamente.
Pd
Eu ainda mantenho o que estou dizendo. Altere a Arquitetura para o que a empresa quiser chamar e altere os testes de unidade para testes de regressão (automatizados?) E ela se aplica.
Paul
@ Paul: Desculpe, eu não estou seguindo. Que documento interessante você acha que estou sugerindo é ruim?
Pd
0

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.

Karl Bielefeldt
fonte
0

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.

Classe abstrata
fonte