Diminui as chances de algo dar terrivelmente errado durante a implementação e mesmo depois de lançar seu produto.
Como engenheiro de software, seu principal papel é resolver problemas técnicos. Seu primeiro impulso pode ser imediatamente saltar direto para o código de escrita. Mas isso pode ser uma péssima ideia se você não pensou na sua solução.
Você pode pensar através de problemas técnicos difíceis escrevendo uma especificação técnica. Escrever um pode ser frustrante se você se sentir como se não fosse um bom escritor. Você pode até pensar que é uma tarefa desnecessária. Mas escrever uma especificação técnica aumenta as chances de ter um projeto, serviço ou recurso bem-sucedido com o que todas as partes interessadas envolvidas estão satisfeitas. Diminui as chances de algo dar terrivelmente errado durante a implementação e mesmo depois de lançar seu produto.
Neste artigo, vou te acompanhar como escrever uma especificação técnica que garanta um produto forte.
O que é um documento de especificação técnica?
Um documento de especificação técnica descreve como você vai resolver um problema técnico projetando e construindo uma solução para ele. Às vezes também é referido como um documento de design técnico, um documento de design de software ou um documento de projeto de engenharia. Muitas vezes é escrito pelo engenheiro que construirá a solução ou será a pessoa pontual durante a implementação, mas para projetos maiores, ela pode ser escrita por leads técnicos, leads de projeto ou engenheiros seniores. Esses documentos mostram à equipe do engenheiro e a outros stakeholders qual será o projeto, o trabalho envolvido, o impacto e o cronograma de um recurso, projeto, programa ou serviço.
Por que escrever uma especificação técnica é importante?
As especificações técnicas têm imensos benefícios para todos os envolvidos em um projeto: os engenheiros que as escrevem, as equipes que as utilizam, até mesmo os projetos que são projetados a partir deles. Aqui estão algumas razões pelas quais você deve escrever um.
Benefícios para engenheiros
Ao escrever uma especificação técnica, os engenheiros são forçados a examinar um problema antes de ir direto para o código, onde eles podem ignorar algum aspecto da solução. Quando você quebra, organiza e cronometra todo o trabalho que você terá que fazer durante a implementação, você tem uma visão melhor do escopo da solução. As especificações técnicas, por serem uma visão minuciosa da solução proposta, também servem de documentação para o projeto, tanto para a fase de implementação quanto posteriormente, para comunicar suas realizações sobre o projeto.
Com esta solução bem pensada, sua especificação técnica o salva de explicar repetidamente seu design para vários colegas de equipe e partes interessadas. Mas ninguém é perfeito. seus pares e engenheiros mais experientes podem mostrar-lhe coisas novas a partir deles sobre design, novas tecnologias, práticas de engenharia, soluções alternativas, etc. que você pode não ter se deparado ou pensado antes. Eles podem pegar casos excepcionais da solução que você pode ter negligenciado, reduzindo sua responsabilidade. Quanto mais olhos você tiver em sua especificação, melhor.
Benefícios para uma equipe
Uma especificação técnica é uma maneira simples e eficiente de comunicar ideias de design de projetos entre uma equipe e outras partes interessadas. Toda a equipe pode resolver um problema de forma colaborativa e criar uma solução. À medida que mais colegas de equipe e partes interessadas contribuem para uma especificação, isso os torna mais investidos no projeto e os incentiva a assumir a propriedade e a responsabilidade por ele. Com todos na mesma página, limita complicações que podem surgir de trabalhos sobrepostos. Colegas mais novos que não estão familiarizados com o projeto podem embarcar e contribuir para a implementação mais cedo.
Benefícios para um projeto
Investir em uma especificação técnica resulta, em última análise, em um produto superior. Como a equipe está alinhada e de acordo com o que precisa ser feito através da especificação, grandes projetos podem progredir mais rápido. Uma especificação é essencial para gerenciar a complexidade e prevenir o escopo e o arrepio de recursos, estabelecendo limites de projeto. Ele estabelece prioridades, garantindo que apenas as partes mais impactantes e urgentes de um projeto saiam primeiro.
Após a implementação, ajuda a resolver problemas que surgiram dentro do projeto, além de fornecer insights em retrospectivas e postmortems. As melhores especificações planejadas servem como um grande guia para medir o sucesso e o retorno sobre o investimento do tempo de engenharia.
O que fazer antes de escrever uma especificação técnica
Reúna as informações existentes no domínio do problema antes de começar. Leia sobre quaisquer requisitos de produto/recurso que a equipe do produto tenha produzido, bem como requisitos/padrões técnicos associados ao projeto. Com esse conhecimento da história do problema, tente afirmar o problema em detalhes e pensar em todos os tipos de soluções que você possa pensar que possam resolvê-lo. Escolha a solução mais razoável de todas as opções que você criou.
Lembre-se que você não está sozinho nesta tarefa. Pergunte a um engenheiro experiente que tenha conhecimento sobre o problema para ser sua placa de som. Convide-os para uma reunião e explique o problema e a solução que você escolheu. Desça suas ideias e processo de pensamento e tente convencê-los de que sua solução é a mais apropriada. Reúna seus feedbacks e peça que eles sejam revisores de sua especificação técnica.
Finalmente, é hora de realmente escrever a especificação. Bloqueie o tempo em seu calendário para escrever o primeiro rascunho da especificação técnica. Use um editor de documentos colaborativo ao que toda a sua equipe tem acesso. Obtenha um modelo de especificação técnica (veja abaixo) e escreva um rascunho bruto.
Conteúdo de uma especificação técnica
Há uma ampla gama de problemas sendo resolvidos por um grande número de empresas hoje. Cada organização é distinta e cria sua própria cultura de engenharia única. Como resultado, as especificações técnicas podem não ser padrão mesmo dentro de empresas, divisões, equipes e até mesmo entre engenheiros da mesma equipe. Cada solução tem necessidades diferentes e você deve adaptar sua especificação técnica com base no projeto. Você não precisa incluir todas as seções mencionadas abaixo. Selecione as seções que funcionam para o seu design e desista do resto.
Pela minha experiência, há sete partes essenciais de uma especificação técnica: matéria de frente, introdução, soluções, considerações adicionais, avaliação de sucesso, trabalho, deliberação e matéria final.
1. Matéria frontal
Título
Autor(s)
Equipe
Revisores
Criado em
Última atualização
Link de referência épico, ticket, edição ou rastreador de tarefas
2. Introdução
a. Visão geral, Descrição do problema, resumo ou resumo
Resumo do problema (da perspectiva do usuário), do contexto, da solução sugerida e das partes interessadas.
B. Glossário ou Terminologia
Novos termos que você se depara ao pesquisar seu design ou termos que você pode suspeitar que seus leitores/partes interessadas não saibam.
c. Contexto ou Fundo
Razões pelas quais o problema vale a pena resolver
Origem do problema
Como o problema afeta usuários e metas da empresa
Esforços passados feitos para resolver a solução e por que eles não eram eficazes
Como o produto se relaciona com metas da equipe, OKRs
Como a solução se encaixa no roteiro e estratégia geral do produto
Como a solução se encaixa na estratégia técnica
d. Metas ou Requisitos De Produto e Técnico
Requisitos do produto na forma de histórias de usuários
Requisitos técnicos
e. Não-Objetivos ou Fora de Escopo
Requisitos técnicos e de produtos que serão desconsiderados
f. Metas futuras
Requisitos técnicos e de produtos programados para um tempo futuro
G. Suposições
Condições e recursos que precisam estar presentes e acessíveis para que a solução funcione como descrito.
3. Soluções
a. Solução atual ou existente / Design
Descrição atual da solução
Prós e contras da solução atual
B. Solução /Design sugerido ou proposto
Componentes externos com os quais a solução interagirá e que ela irá alterar
Dependências da solução atual
Prós e contras da solução proposta
Mudanças no modelo de dados / esquema
Definições de esquema
Novos modelos de dados
Modelos de dados modificados
Métodos de validação de dados
Lógica empresarial
Alterações da API
Pseudocódigo
Fluxogramas
Estados de erro
Cenários de falha
Condições que levam a erros e falhas
Limitações
Camada de apresentação
Requisitos do usuário
Mudanças de UX
Alterações na interface do usuário
Wireframes com descrições
Links para o trabalho do designer UI/UX
Preocupações móveis
Preocupações com a Web
Estados de interface do usuário
Manipulação de erros
Outras perguntas a responder
Como a solução vai dimensionar?
What are the limitations of the solution?
Como ele vai se recuperar em caso de falha?
Como ele vai lidar com os requisitos futuros?
c. Plano de Teste
Explicações de como os testes garantirão que os requisitos do usuário sejam atendidos
Testes unitários
Testes de integrações
Qa
d. Plano de Monitoramento e Alerta
Plano de registro e ferramentas
Plano de monitoramento e ferramentas
Métricas a serem usadas para medir a saúde
Como garantir a observância
Plano de alerta e ferramentas
e. Plano de Lançamento / Implantação e Implantação
Arquitetura de implantação
Ambientes de implantação
Plano de implantação em fases, por exemplo, usando bandeiras de recursos
Planeje como comunicar alterações aos usuários, por exemplo, com notas de lançamento
f. Plano de reversão
Passivos detalhados e específicos
Plano para reduzir passivos
Planeje como evitar que outros componentes, serviços e sistemas sejam afetados
g. Soluções Alternativas / Projetos
Instrução de resumo curto para cada solução alternativa
Prós e contras para cada alternativa
Razões pelas quais cada solução não poderia funcionar
Formas em que as alternativas eram inferiores à solução proposta
Plano de migração para a próxima melhor alternativa caso a solução proposta caia
4. Outras Considerações
Um. Impacto em outras equipes
Como isso vai aumentar o trabalho de outras pessoas?
B. Considerações de serviços e plataformas de terceiros
Vale mesmo a pena em comparação com a construção do serviço em casa?
Quais são algumas das preocupações de segurança e privacidade associadas aos serviços/plataformas?
Quanto vai custar?
Como vai escalar?
Que possíveis questões futuras estão previstas?
c. Análise de custos
Qual é o custo para executar a solução por dia?
Quanto custa para distribuá-lo?
d. Considerações de segurança
Quais são as ameaças em potencial?
Como eles serão mitigados?
Como a solução afetará a segurança de outros componentes, serviços e sistemas?
e. Considerações de privacidade
A solução segue as leis locais e as políticas legais sobre privacidade de dados?
Como a solução protege a privacidade de dados dos usuários?
Quais são algumas das trocas entre personalização e privacidade na solução?
F. Considerações regionais
Qual é o impacto da internacionalização e da localização na solução?
Quais são os problemas de latência?
Quais são as preocupações legais?
Qual é o estado de disponibilidade de serviços?
Como a transferência de dados entre as regiões será alcançada e quais são as preocupações aqui?
G. Considerações de acessibilidade
Quão acessível é a solução?
Quais ferramentas você usará para avaliar sua acessibilidade?
H. Considerações operacionais
Essa solução causa efeitos adversos posteriores?
Como os dados serão recuperados em caso de falha?
Como a solução se recuperará em caso de falha?
Como os custos operacionais serão mantidos baixos enquanto entregam maior valor aos usuários?
i. Riscos
Quais os riscos que estão sendo empreendidos com essa solução?
Há riscos que uma vez tomados não podem ser levados de volta?
Qual é a análise custo-benefício de assumir esses riscos?
J. Considerações de suporte
Como a equipe de suporte vai passar informações aos usuários sobre problemas comuns que eles podem enfrentar enquanto interagem com as mudanças?
Como garantir que os usuários estejam satisfeitos com a solução e possam interagir com ela com suporte mínimo?
Quem é o responsável pela manutenção da solução?
Como será realizada a transferência de conhecimento se o proprietário do projeto não estiver disponível?
B. Métricas
Lista de métricas para capturar
Ferramentas para capturar e medir métricas
6. Trabalho
Um. Estimativas de trabalho e cronogramas
Lista de tarefas específicas, mensuráveis e com tempo
Recursos necessários para concluir cada tarefa
Estimativas de tempo para quanto tempo cada tarefa precisa ser concluída
B. Priorização
Categorização das tarefas por urgência e impacto
c. Marcos
Postos de controle datados quando partes significativas do trabalho terão sido concluídas
Métricas para indicar a passagem do marco
d. Trabalho futuro
Lista de tarefas que serão concluídas no futuro
7. Deliberação
Um. Discussão
Elementos da solução que os membros da equipe não concordam e precisam ser mais debatidos para chegar a um consenso.
b. Perguntas abertas
Perguntas sobre coisas que você não sabe as respostas ou não tem certeza de que você posa para a equipe e as partes interessadas para sua contribuição. Estes podem incluir aspectos do problema que você ainda não sabe como resolver.
8. Matéria final
a. Trabalho relacionado
Qualquer trabalho externo à solução proposta que seja semelhante a ela de alguma forma e é trabalhado por diferentes equipes. É importante saber disso para permitir o compartilhamento de conhecimento entre essas equipes diante de problemas relacionados.
B. Referências
Links para documentos e recursos que você usou ao criar seu design e deseja creditar.
c. Reconhecimentos
Creditar pessoas que contribuíram para o projeto que você deseja reconhecer.
Depois de escrever sua especificação técnica
Agora que você tem uma especificação escrita, é hora de refiná-la. Revise seu rascunho como se fosse um revisor independente. Pergunte a si mesmo quais partes do design não estão claras e você está incerto sobre. Modifique seu rascunho para incluir esses problemas. Revise o rascunho uma segunda vez como se você tivesse a tarefa de implementar o projeto apenas com base apenas na especificação técnica. Certifique-se de que a especificação é uma diretriz de implementação clara o suficiente em que a equipe pode trabalhar se você não estiver disponível. Se você tem dúvidas sobre a solução e gostaria de testá-la apenas para ter certeza de que funciona, crie um protótipo simples para provar seu conceito.
Quando você analisar minuciosamente, envie o rascunho para sua equipe e as partes interessadas. Dirija-se a todos os comentários, perguntas e sugestões o mais rápido possível. Estabeleça prazos para fazer isso para cada questão. Agendar reuniões para falar sobre questões sobre as que a equipe está dividida ou está tendo discussões extraordinariamente longas sobre o documento. Se a equipe não concordar com um problema, mesmo depois de ter reuniões presenciais para avogo-los, faça a chamada final sobre ele como o dinheiro pára com você. Solicite engenheiros em diferentes equipes para revisar sua especificação para que você possa obter uma perspectiva de um estranho que irá melhorar a forma como ele se depara com as partes interessadas que não fazem parte da equipe. Atualize o documento com quaisquer alterações no projeto, cronograma, estimativas de trabalho, escopo, etc. mesmo durante a implementação.
Conclusão
Escrever especificações de teste pode ser uma maneira impactante de garantir que seu projeto será bem sucedido. Um pouco de planejamento e um pouco de previsão podem tornar a implementação real de um projeto muito mais fácil.
