Qual é a maneira correta de criar documentos de requisitos?

No momento, meu supervisor está criando documentação / especificações de requisitos para mim usando o software de rastreamento de bugs. Parece-me uma péssima ideia, todos os requisitos estão nesses pequenos tíquetes e eu tenho que clicar neste formulário da Web idiota para chegar aos requisitos. O que é uma solução de software são para requisitos / especificações de software?

Para deixar claro, estou construindo esse grande componente de software com alguns recursos e esses recursos estão sendo estabelecidos neste software de rastreamento de erros.

Estou bastante surpreso que ninguém até agora tenha recomendado o uso de um wiki para rastrear requisitos.

Eu achei que era um sistema quase perfeito, porque:

• Ele permite que as pessoas colaborem nos requisitos e torna esse aspecto altamente visível;
• Permite manter facilmente os requisitos atualizados à medida que o projeto avança;
• Você pode entrar e ver a história a qualquer momento, no caso de uma disputa "não é isso que concordamos";
• A maioria dos wikis modernos possui recursos de formatação decentes, por isso parece quase tão bom quanto um documento do Word;
• Você pode vincular diretamente seus requisitos à documentação real;
• Você nunca precisa se preocupar com pessoas trabalhando com cópias diferentes / obsoletas;
• Os requisitos podem começar a ser tratados como um processo iterativo, assim como o design / implementação;
• Se os requisitos começarem a ficar realmente grandes / complicados, é fácil dividi-los em páginas / tópicos.
• A maioria dos wikis aceita HTML; portanto, se você realmente precisar de formatação avançada, provavelmente poderá usar uma ferramenta como o Windows Live Writer .

Dada a escolha, eu quase sempre escolho o método wiki hoje em dia, é realmente bastante indolor comparado aos documentos antiquados do Word ou tentando colocar tudo em um rastreador de erros.

Eu sempre uso o IEEE Std 830-1998 (Prática recomendada pelo IEEE para especificações de requisitos de software) como modelo para o meu documento SRS. Consulte http://standards.ieee.org/reading/ieee/std_public/description/se/830-1998_desc.html

O próprio documento final do SRS geralmente é um único documento do OpenOffice.org, mas geralmente existem muitas partes constituintes, incluindo planilhas e diagramas.

Eu costumo reunir todos esses documentos em um repositório que coloco em um sistema de controle de revisão , como SVN ou CVS. Todos os outros analistas de negócios, designers, desenvolvedores, testadores, gerentes de projeto e clientes têm acesso a esse repositório, para que possam lê-lo e fazer edições.

Lembre-se, o SRS é um documento vivo e em evolução. Continuará a mudar e crescer por algum tempo. Não apenas é importante que todas as partes interessadas tenham acesso ao SRS, mas também é importante ter um histórico completo das alterações e a capacidade de reverter essas alterações também, se necessário. Portanto, um sistema de controle de revisão funciona muito bem para esse fim. Boa sorte!

O uso do rastreador de erros para gerenciamento de requisitos tem a tendência de ocultar a falta de colaboração e comunicação dentro da empresa.

Sem julgar qualquer método específico:

• se você usar o cascata, precisará de documentos bem estruturados, precisos e com várias páginas (não um parágrafo que muitas pessoas digitam normalmente como descrição de um bug). Também é impossível escrever e manter esses documentos em um nível decente de qualidade se os vendedores / marketing (que originam os requisitos) não funcionarem bem em conjunto com a equipe de engenharia.
• se você usar um dos métodos ágeis, uma unidade de requisitos será uma história do usuário, representada por um cartão de história. O cartão em si não é um requisito, apenas um ponto de partida da conversa.

Uma (breve) experiência de um de meus empregadores anteriores com o uso de um rastreador de erros para os requisitos foi que ele proporcionou a muitas pessoas uma maneira muito fácil de parar de se comunicar completamente. As pessoas simplesmente escreviam um desejo, o despejavam no rastreador de erros e supunham que ele acabaria se tornando realidade.

É claro que eles fizeram isso sem levar em consideração:

• suas próprias qualificações
• sua participação no projeto
• conflita com outros requisitos
• lacunas nos requisitos
• custos
• quaisquer considerações técnicas
• etc.

Acredito que os documentos "Word" são o caminho errado para os requisitos, pelos seguintes motivos:

1. Não há como "diferenciar" dois documentos para ver o que mudou.
2. A interface do usuário desencoraja o uso de um estilo consistente. Sim, o uso de estilos pode ser feito, mas a maioria das pessoas não pode ser incomodada por causa da dificuldade.
3. O formato do documento está essencialmente oculto. Claro, há uma especificação para arquivos OLE, que eu acho que os documentos do "Word" são, mas a Microsoft escondeu tudo o que é útil sob toneladas de tolices, para que ninguém realmente saiba. Mais cedo ou mais tarde, seu novo e brilhante "Word" não abrirá o documento.
4. Não joga bem com outros formatos. Ou seja, a menos que você use o Windows e o IE, você não terá sorte se alguém organizar os documentos de um projeto em arquivos HTML com links para os arquivos no formato "Word". Clique no link errado e você terá que passar por um longo período de download e início do Word, interrompendo o fluxo de pensamentos. Hiperlinks de documentos do "Word" para outras pessoas podem ou não funcionar.
5. "Word" é basicamente para escrever documentos destinados a aparecer no papel. Um objetivo admirável, mas que o torna menos que útil para a visualização on-line.

Não tenho uma sugestão alternativa com a qual tenho experiência, mas pensei no texto reestruturado ou no Markdown do Python como alternativas.

Geralmente usamos o Word, mas, na realidade, como você os cria em software é menos importante do que como você coleta os dados para criá-los e se a pessoa que coleta as informações sabe o suficiente para saber quando um requisito é excessivamente complicado e será muito mais caro do que um requisito mais simples ainda não agrega valor real a ninguém (como quando eles desejam que os números de ID sempre sejam atribuídos em ordem, sem que nenhum seja ignorado) ou quando entram em conflito com um requisito existente ou outro recurso planejado. Freqüentemente, os usuários reais nunca são conversados ​​e há muitas surpresas quando seus gerentes não sabiam algo que absolutamente precisava ser feito e não está na nova versão do software.

Também podemos usar vários arquivos pdf, Excel ou Visio. Todos eles para o projeto são coletados e editados no SharePoint, para que possamos ver versões anteriores, se necessário.

Eu mantenho uma lista de pendências de produtos (uma por projeto ou produto) que contém Histórias de Usuários . Eles podem ser armazenados em um software de rastreamento de erros, como o que você usa. Pessoalmente, uso o Excel para o backlog e o Trac para o sprint (você provavelmente usa uma ferramenta como essa).

Quando necessário, eu crio um documento do Word que descreve a história do usuário com mais detalhes e a anexo à história do usuário. Mas tento evitar isso dividindo a história do usuário em outras menores.

Histórias de usuário pequenas são mais fáceis de gerenciar (incluindo estimativa)

Gosto do documento do Word porque ele permite que eu coloque links, formate textos, coloque tabelas, capturas de tela e muito mais, e todos possam lê-lo.

Obviamente, cada história de usuário é explicada em detalhes na sessão de estimativa e no planejamento de sprint, e eu estou sempre disponível para mais perguntas quando o desenvolvedor decide trabalhar nela. Os feedbacks frequentes usando a revisão do sprint impedem que os desenvolvedores façam algo diferente do solicitado pelo proprietário do produto.

Pessoalmente, no passado eu usei o Word Documents, mas resolvi encontrar uma ferramenta no futuro para gerenciar isso para mim ... especialmente com a capacidade de definir bugs para os requisitos, porque, na maioria das vezes, o bug é nos requisitos, não no desvio entre especificações e implementação.

Nunca me ocorreu usar uma ferramenta de rastreamento de bugs, mas faz total sentido.

Por curiosidade, do que você não gosta?

EDIT: uma ressalva; diga ao seu gerente para renomear o software de rastreamento de bugs. Caso contrário, tudo é considerado um bug. Eu tive esse problema político no meu último cliente, onde coloquei tarefas no rastreador de erros. Não é bom.

Eu escrevi um banco de dados de requisitos há 6 ou 7 anos para lidar com isso. Cada registro de requisito possui uma descrição curta, um memorando de "definição" e um memorando de "notas" (ambos em rich text, com capacidade de incorporar capturas de tela etc.). Também existem outros campos, para projeto, entrega, número de sequência (para que possam ser solicitados logicamente), caso de uso / recurso a que está relacionado, estimativa de tempo, um campo para a pessoa que o manipula, se alguém o selecionou para implementação, etc.

Há também um "Status" - "Entered", pois enquanto projetamos os recursos; "Aprovado", definido quando um grupo de requisitos é revisado e determinado como pronto para implementar; "Implementado", definido pelo programador assim que achar que o requisito foi cumprido e "Validado" quando a técnica de controle de qualidade concordar com o programador. (Se o técnico de controle de qualidade discordar, ele pode defini-lo como "Aprovado" para que o programador o recupere.) Os requisitos também podem ser "Adiados", "Rejeitados" ou "Questionados" (o que significa que o Change Control Board precisa analisá-lo .)

O truque para fazer isso bem é uma granularidade razoável. Às vezes, pode fazer sentido ter requisitos de uma frase (por exemplo, "o problema descrito no problema 12345 foi corrigido"), mas, em geral, os requisitos devem descrever todos os aspectos importantes de um recurso inteiro (ou um grande pedaço). Por exemplo, um recurso típico de "novo relatório" terá um requisito para um formato de relatório (como é a saída) e um requisito para a caixa de diálogo de opções (explicando os campos, validação etc.). existe um gerador complexo que processa os dados, em vez de apenas uma consulta fácil ou algo assim. Além disso, criaremos um requisito de "Ajuda" para o tópico de ajuda correspondente.

Existem enormes vantagens em manter esse material nos registros do banco de dados, em vez de um grande documento. Vários programadores podem trabalhar nos requisitos ao mesmo tempo. Os registros individuais são bloqueados para que apenas uma pessoa possa editar de cada vez, mas eles podem ser abertos e lidos enquanto outra pessoa estiver editando. A maior vantagem, porém, é que ele facilita a pesquisa na documentação de quais eram os requisitos e anotações sobre como eles foram implementados. Temos mais de 25.000 requisitos lá agora, e podemos encontrar facilmente todos os requisitos com palavras específicas em todos os campos, ou na definição, ou notas, ou o que for, em menos de 10 segundos. (Tente isso com mais de 6 anos de documentos do Word.)

Percebo por que as pessoas podem dizer que é uma má idéia fazer requisitos em um "rastreador de erros", mas acho que é porque as ferramentas são ruins, não porque manter os requisitos em um banco de dados pesquisável é uma má idéia.

Eu usei uma vez http://www.pivotaltracker.com/, mas na minha empresa atual estamos usando .doc como fonte de especificação principal e Lighthouse como recursos combinados, lista de desejos e rastreamento de problemas. Para mim, é difícil fazer com que outras pessoas da equipe comecem a usar outras ferramentas quando estão muito acostumadas ao Word.

Se você pode seguir a metodologia Agile, os seguintes links podem orientá-lo na escolha de uma boa ferramenta Agile Project Management:

• Ferramentas de Gerenciamento Ágil de Projetos
• Comparação de diferentes ferramentas ágeis de gerenciamento de projetos

E, sério, tente a metodologia Agile - ela prega uma abordagem sensorial comum, simples, elegante, sem bobagens, sem jazz e em qualquer coisa que você faça, de modo que cada membro da equipe entenda e aprecie o papel e o esforço de todos os outros membros.

Boa sorte!