Especificação técnica de uma aplicação: modelo e exemplo

Um caderno de requisitos deve evitar interpretações diferentes

Uma aplicação para reservar aulas parece fácil de explicar: consultar o horário, escolher uma sessão e pagar. Mais tarde percebe-se que o responsável esperava uma lista de espera, o designer imaginou uma confirmação imediata e a equipa técnica não sabe o que fazer quando o pagamento é confirmado depois de a reserva expirar.

O caderno de requisitos serve para esclarecer estas diferenças antes de começarem a gerar trabalho adicional. Deve explicar quem utiliza a aplicação, o que pretende fazer, quais são as regras e como se verifica o resultado. Não exige que o cliente escolha sozinho a arquitetura. As perguntas ainda sem resposta também pertencem ao documento.

Pode começar pelo modelo editável de especificação. É um ficheiro de texto em formato Markdown, disponível sem registo. O exemplo que se segue descreve um estúdio de aulas fictício. É uma demonstração do método, não a apresentação de um projeto de um cliente.

Separar a apresentação da ideia, os requisitos e a proposta

A apresentação inicial explica a ideia. A especificação transforma as decisões importantes em requisitos que o design, o desenvolvimento e os testes conseguem utilizar. A proposta identifica os trabalhos, os pressupostos e as dependências. Os três documentos devem descrever a mesma primeira versão, mas respondem a perguntas diferentes.

Se ainda não sabe quem será o primeiro público ou qual será a função principal, comece por preparar o pedido de avaliação. Dizer que uma decisão está em aberto é perfeitamente aceitável. O problema aparece quando uma das partes considera essa decisão fechada e a outra nunca recebeu essa informação.

Escolha uma pessoa para manter a versão atualizada. Não precisa de decidir tudo sozinha. Deve registar os acordos, retirar instruções antigas e avisar quando uma alteração afeta o âmbito do trabalho ou os testes. Várias versões contraditórias são mais difíceis de gerir do que um documento com perguntas por resolver.

Que secções vale a pena preencher

Uma pessoa que não participou nas primeiras reuniões deve conseguir compreender o serviço. As maquetas e a documentação técnica podem ficar em ligações. As decisões essenciais, porém, não devem desaparecer entre anexos dispersos.

“Precisamos de uma base de dados” não esclarece o comportamento do produto. “A administração consegue consultar reservas canceladas, o motivo e quem fez a alteração” é uma indicação muito mais útil. A equipa pode propor a solução técnica depois de compreender essa necessidade.

Exemplo preenchido: reservar uma aula num pequeno estúdio

O nosso estúdio fictício recebe atualmente as inscrições por mensagens. A primeira aplicação destina-se aos clientes existentes de uma única localização. Permite consultar sessões, reservar um lugar, pagar e voltar a encontrar a confirmação. O professor vê os participantes. A administração cria aulas e trata cancelamentos.

Ficam de fora, por enquanto, os planos de adesão, a lista de espera, os pagamentos a professores, as funções sociais e outras localizações. Não se trata de rejeitar essas ideias. Primeiro queremos saber se o percurso principal reduz o trabalho manual sem obrigar a resolver vários modelos de funcionamento ao mesmo tempo.

A regra mais importante está entre a reserva e o pagamento. A inscrição só fica confirmada depois de o sistema receber um resultado de pagamento válido. Durante o processo, o lugar pode ser guardado por um período acordado. Quando o prazo termina, volta a ficar disponível. A duração deve ser decidida pelo negócio com a equipa, não escolhida casualmente no código.

E se a confirmação chegar tarde, quando o lugar já foi libertado? A aplicação não pode ultrapassar silenciosamente a capacidade. O documento deve explicar a solução escolhida, a mensagem ao cliente e a ação disponível para a administração. Este caso revela mais trabalho real do que outra coleção de ecrãs.

Escrever critérios de aceitação que se conseguem testar

Um critério de aceitação diz como reconhecer que um requisito foi cumprido. Pode usar linguagem corrente. O guia GOV.UK sobre histórias de utilizador ajuda a enquadrar o método, mas os critérios devem descrever o seu próprio serviço.

Para o último lugar, dois clientes abrem a mesma aula em simultâneo. O primeiro obtém uma reserva temporária válida. O segundo vê que já não há disponibilidade e não avança para um pagamento que não pode terminar numa inscrição. Após a confirmação do primeiro pagamento, aparece apenas uma reserva na lista.

Depois teste uma interrupção. O cliente fecha a aplicação durante o pagamento e volta a abri-la. A aplicação consulta o estado real, em vez de presumir uma falha porque o ecrã final não apareceu. Uma notificação repetida do prestador de pagamentos não cria outra reserva. Vários toques também não devem duplicar a operação.

Defina ainda a prova necessária. Quem aceita a entrega deve conseguir relacionar a reserva, o estado do pagamento e a vista administrativa. Uma captura de ecrã com uma mensagem positiva não demonstra, por si só, que o lugar ficou ocupado corretamente.

A administração faz parte do produto desde o início

Alguém terá de cancelar uma aula, verificar um pagamento ou corrigir uma inscrição. Pode ser o professor? Tem acesso apenas às suas sessões? Quem altera a capacidade? O apoio ao cliente consegue perceber por que motivo uma reserva foi modificada manualmente?

Estas perguntas ficam facilmente atrás dos ecrãs destinados ao cliente. No funcionamento diário são fundamentais. Se cada situação habitual exige que um programador altere os dados de produção, o negócio ainda não consegue utilizar a aplicação com autonomia.

Descreva as ações necessárias, as permissões e as confirmações de operações sensíveis. Comece pelo primeiro dia de utilização. O guia do painel de administração ajuda a organizar a conversa, mas não é preciso incluir todas as funções possíveis na primeira versão.

Identificar as dependências de cada integração

“Ligar ao sistema de horários” é uma descrição incompleta. Indique qual é o sistema, quem disponibiliza documentação, se há acesso de teste e que fonte prevalece quando os dados não coincidem.

No exemplo, o cancelamento de uma aula deve chegar à aplicação. Se a ligação falhar, talvez seja possível mostrar uma cópia guardada do horário e impedir temporariamente novas reservas. Uma limitação explicada é preferível a confirmar um lugar com informação desatualizada.

Separe também os dados necessários daqueles que seria apenas possível recolher. Defina os acessos e as questões de conservação ou eliminação que precisam de análise especializada. Não copie um prazo jurídico de outro projeto. A referência OWASP MASVS apoia a revisão técnica de segurança, mas não substitui as decisões próprias do produto.

Descrever as falhas como a pessoa as vai viver

Um horário vazio, um pagamento recusado ou uma sessão de acesso expirada fazem parte da utilização normal. A instrução “mostrar erro” não esclarece se os dados introduzidos ficam guardados nem o que a pessoa pode fazer a seguir.

Percorra a tarefa principal e assinale os pontos em que alguém pode perder acesso, dinheiro, trabalho ou confiança no serviço. Para cada um deve existir uma saída compreensível: consultar o estado, tentar novamente, regressar a um passo anterior ou pedir ajuda. Não é necessário inventar centenas de situações sem impacto real.

A acessibilidade também merece requisitos concretos. A seleção é reconhecível sem depender apenas da cor? O botão continua acessível quando o texto aumenta? Um leitor de ecrã anuncia o estado da reserva? A introdução do W3C à acessibilidade oferece um ponto de partida; a verificação deve depois acontecer nos ecrãs reais.

O que a primeira entrega precisa de demonstrar

Para o estúdio, o sucesso não se resume ao número de instalações. Os clientes devem concluir reservas corretas, e a equipa deve geri-las sem reconstruir o processo através de mensagens.

Escolha poucos eventos de análise e defina o significado de cada um. Uma reserva concluída corresponde a uma confirmação efetiva, não ao primeiro toque num botão. Nomes e parâmetros comuns evitam que iOS, Android e o servidor registem situações diferentes com a mesma designação.

Antes de aceitar a entrega, faça o percurso completo numa versão próxima da publicação: instalação, entrada na conta, reserva bem-sucedida, pagamento falhado, cancelamento e ação administrativa. A lista de testes da aplicação permite repetir a revisão com critérios consistentes.

Alterar o documento sem perder o acordo

Os requisitos tornam-se mais claros durante o projeto. Convém distinguir um esclarecimento, a correção de um defeito e uma função nova. Melhorar um texto confuso não é equivalente a acrescentar pagamentos a professores ou lançar noutro país.

Para uma mudança importante, registe o motivo, o percurso afetado, as consequências e a decisão. Retire as instruções antigas. Se o âmbito mudar, peça uma revisão dos pressupostos antes de continuar. É muito mais simples conversar nessa altura do que discutir duas interpretações durante a demonstração final.

A Appfyl pode usar este documento como base de trabalho. Consulte os nossos exemplos de produtos e envie a informação pelo questionário do projeto. O resultado pretendido é uma primeira versão compreendida e verificável por todos, não um documento maior.

Preencher o modelo sem fingir que todas as respostas existem

Abra o modelo editável e comece por uma pessoa, um objetivo e um percurso inteiro. No estúdio fictício: «A cliente escolhe uma aula, paga, recebe confirmação e encontra a reserva mais tarde». Esta frase esconde decisões: quando é que o lugar fica reservado? Quem pode cancelar? O que acontece se a confirmação do pagamento chegar atrasada? Escreva cada dúvida com a pessoa responsável pela resposta. Um campo vazio parece facilmente um acordo; uma pergunta registada obriga a conversar.

Peça ao responsável pelo estúdio e à futura equipa de desenvolvimento que leiam a primeira versão separadamente. Mais importante do que ambos dizerem «está bem» é descobrir onde imaginaram comportamentos diferentes. Se os professores esperam poder alterar horários, mas o documento reserva a ação à administração, resolva a divergência antes de fechar o âmbito. Coloque referências visuais e acessos em anexos; o documento principal deve ser compreensível sem abrir dez ficheiros.

Pode iniciar uma proposta com questões por responder, desde que os pressupostos usados fiquem claros. Os critérios de aceitação podem ser refinados durante a preparação, mas precisam de acordo antes de a funcionalidade ser dada como concluída. Dessa forma, o modelo continua a ser uma ferramenta de trabalho e não apenas um documento bonito que ninguém volta a consultar.

Perguntas frequentes