O que gere além do documento?
Um documento é apenas uma forma de registar uma decisão. Também é necessário saber quais os pontos acordados, quais ainda são propostas, quem responderá às perguntas e o que muda quando um ponto é revisto. Isto ajuda a evitar que se trabalhe com base em interpretações diferentes do mesmo pedido.
A mesma abordagem pode ajudar no desenvolvimento de aplicações, ferramentas internas, condições de produto e regras operacionais. Comece por uma funcionalidade ou fluxo de trabalho, em vez de tentar documentar tudo de uma só vez.
Ligue o objetivo, requisito, especificação e critérios de aceitação
As equipas utilizam estes termos de formas diferentes. Neste exemplo, um requisito descreve um resultado necessário ou uma restrição, uma especificação regista o comportamento acordado e os critérios de aceitação explicam como o verificar. Acorde estes significados com as pessoas com quem trabalha.
Objetivo: reduzir a transcrição manual
Atualmente, o processo de relatórios mensais exige a cópia manual de registos. O objetivo da exportação é facilitar esse trabalho.
Requisito: exportar os registos necessários para o relatório
Um membro da equipa precisa de exportar os registos de um mês escolhido, dentro do âmbito a que tem autorização de acesso.
Especificação: defina o ficheiro e o seu comportamento
Defina em conjunto as colunas, a ordem, a codificação de texto, o formato de data, o comportamento quando não há resultados e os erros. Estas são escolhas para este exemplo, não predefinições universais.
Critérios de aceitação: torne o resultado verificável
Prepare registos com datas e permissões conhecidas, efetue a exportação e compare o resultado com o que foi acordado.
Escreva uma ideia verificável por item
Uma expressão como «Tornar a exportação conveniente» deixa decisões importantes em aberto. Separe a seleção de um período, a escolha dos campos de saída, o tratamento da ausência de correspondências e a verificação do acesso quando estes aspetos puderem ser alterados ou verificados de forma independente.
Utilize condições concretas em vez de palavras como «rápido» ou «fácil». Se uma meta de tempo de resposta for importante, registe a carga de trabalho, o ambiente e o método de medição, além do número. Mantenha os valores ainda não decididos claramente assinalados como tal.
Antes: «Permitir exportação CSV.»
Depois: «Exporte o mês selecionado, utilizando as colunas e a ordem de ordenação acordadas. Defina os resultados vazios e as verificações de acesso em itens separados.»
A redação revista identifica as escolhas que precisam de ser acordadas e facilita a distribuição e a revisão do trabalho. Ainda são necessárias definições concretas dos campos antes da implementação.
Um pequeno conjunto de campos para começar
ID, título e descrição
Atribua a cada item um ID estável, como REQ-001. Indique o assunto, a condição e o resultado esperado. Um ID estável permite referir o item mesmo depois de o título mudar.
Motivo e fonte
Registe o problema que o item resolve e a sua origem, como uma conversa, um pedido ou um documento de apoio.
Prioridade e âmbito
Distinga o que é necessário para esta versão do que pode esperar. Explique o motivo da prioridade; não atribua a prioridade máxima a todos os itens.
Responsável e estado da decisão
Registe quem irá esclarecer o item e se este está em rascunho, em revisão ou acordado. O responsável pela implementação e quem aprova podem ser pessoas diferentes.
Critérios de aceitação e informações relacionadas
Ligue o elemento às especificações, aos designs, às tarefas e aos registos de verificação relevantes. Mantenha essas ligações atualizadas quando os requisitos mudarem.
Exemplo: três requisitos para uma exportação CSV mensal
O seguinte é um exemplo ilustrativo. Os nomes dos campos e o comportamento devem ser acordados para o produto que está a desenvolver; o exemplo não é uma especificação completa de todas as funcionalidades de exportação.
REQ-001: registos do mês selecionado
Exemplo de especificação: utilizar o mês escolhido no fuso horário comercial acordado e exportar o ID, a data do registo e o título em UTF-8, ordenados primeiro por data e depois por ID. Exemplo de aceitação: três registos correspondentes produzem uma linha de cabeçalho e exatamente essas três linhas de dados, sem registos de outros meses.
REQ-002: nenhum registo correspondente
Exemplo de especificação: exportar a linha de cabeçalho acordada mesmo quando não existem registos correspondentes. Exemplo de aceitação: o conjunto de teste vazio produz um ficheiro com esse cabeçalho e sem linhas de dados. Se preferir uma mensagem em vez de um ficheiro, chegue a acordo sobre esse comportamento alternativo e documente-o.
REQ-003: o acesso é verificado antes da exportação
Exemplo de especificação: os utilizadores sem permissão de exportação não podem gerar o ficheiro e os registos fora do âmbito permitido não são incluídos. Os exemplos de aceitação devem abranger um utilizador sem permissão de exportação e outro cujo acesso aos registos é limitado.
Use hierarquias sem perder as decisões individuais
Agrupe os itens por finalidade ou funcionalidade e coloque as condições detalhadas no grupo correspondente. Por exemplo: Relatórios → Exportação mensal de CSV → Registos pretendidos / Formato do ficheiro / Resultados vazios / Acesso. Coloque o contexto e as questões em aberto nas notas, em vez de os misturar num único requisito extenso.
Se uma condição afetar várias funcionalidades, mantenha uma referência clara à versão acordada em vez de copiar versões diferentes para cada secção. Antes de a alterar, verifique quais as especificações posteriores e os itens de verificação que dependem dela.
Mantenha separados o acordo, a implementação e a verificação
«Acordado» significa que o conteúdo foi aceite para o âmbito previsto. Não significa que a funcionalidade tenha sido implementada. «Implementado» não confirma que os critérios de aceitação acordados tenham sido cumpridos nem que a funcionalidade tenha sido lançada. Mantenha estas distinções visíveis, mesmo que utilize uma lista simples de estados.
Reveja o caso normal, as entradas vazias ou em falta, as permissões e as falhas externas, quando relevantes. Decida que provas guardar, quem as verifica e quem pode encerrar uma questão por resolver.
Registe uma alteração e o seu impacto antes de a considerar acordada
Um novo pedido continua a ser uma proposta até que os responsáveis acordem como o tratar. Registe o motivo da alteração, os IDs afetados e o impacto no trabalho, nas datas, nas especificações e na verificação. Considere também se a alteração se aplica a registos ou utilizadores que já usam a funcionalidade.
Após a decisão, atualize a especificação atual e informe as pessoas afetadas. Guarde a versão anteriormente acordada ou uma nota de alteração quando precisar de explicar o que mudou. Não parta do princípio de que uma ferramenta regista automaticamente todas as aprovações e revisões.
Escolha um local que consiga manter atualizado
Para uma lista pequena, um documento ou uma folha de cálculo partilhados podem ser suficientes. Quando a discussão, a implementação e a verificação estão distribuídas por várias ferramentas, escolha uma referência principal e associe-lhe os materiais relacionados. O importante é que todos consigam identificar o conteúdo atualmente acordado.
Use AI para criar um rascunho e depois confirme as decisões
A IA pode ajudar a listar possíveis requisitos, organizar um rascunho e sugerir perguntas em falta. No pedido, separe os factos confirmados dos pressupostos e peça que os valores ainda por decidir sejam deixados como perguntas. Reveja o resultado com as pessoas que conhecem a utilização prevista.
No ReqSpec AI, pode organizar requisitos e especificações hierarquicamente e utilizar a AI para apoiar a criação, edição e verificação. Faça uma pergunta específica, como «Que condições de resultados vazios continuam por definir?». Considere qualquer resposta uma sugestão a verificar face ao conteúdo registado, não uma prova de aprovação ou de completude.
Comece com uma funcionalidade e uma revisão
Escolha uma funcionalidade, enumere os resultados necessários, atribua IDs aos itens e acrescente critérios de aceitação e questões em aberto. Reveja tudo uma vez com uma pessoa relevante e, depois, registe as decisões e o próximo responsável. Um conjunto pequeno e atualizado é mais útil do que um documento extenso que ninguém atualiza.
Organize requisitos e especificações com o ReqSpec AI
O ReqSpec AI oferece uma forma simples de organizar requisitos e especificações no telemóvel e na Web. Explore as funcionalidades na página da aplicação.