Quais são os documentos de um projeto de tecnologia, e para que serve cada um

Seis documentos atravessam um projeto de tecnologia conduzido no modelo tradicional: declaração de escopo, declaração funcional, documentação técnica, caderno de testes, manual do usuário e documento operacional.

Nem todo projeto precisa dos seis. Alguns podem não existir, e outros podem ser absorvidos: a declaração funcional, por exemplo, pode estar contida na declaração de escopo quando o escopo já está bem detalhado.

O que não pode é a informação do projeto se perder no caminho.

Antes de entrar em cada um

Esses são os documentos que eu uso conduzindo projeto tradicional. É possível que existam outros que eu deixei de mencionar, e o conjunto muda conforme a organização.

Vale dizer uma coisa que costuma gerar confusão: documentar não é o oposto de ser ágil. O Manifesto Ágil prefere software funcionando a documentação abrangente, e isso não é o mesmo que ser contra documentação. A pergunta certa não é se documentar, é qual documentação é fundamental e quem vai usá-la.

A coluna que decide isso é a de quem aprova. Documento que ninguém aprova é documento que ninguém defende depois.

Declaração de escopo

Quando o projeto começa, é o primeiro documento a existir. Nele está tudo que será desenvolvido ao longo do projeto.

Normalmente é criado por quem levantou as informações com a equipe ou com o usuário que solicitou a demanda. Não precisa ser um analista de negócios: se quem pediu tem clareza técnica, pode escrever.

Ele serve para auxiliar a condução do projeto, porque expõe as necessidades do cliente, e é imprescindível para a validação no fim.

Como eu uso na prática, e essa é a parte que eu faria diferente de um manual: uso a declaração de escopo como o documento macro do projeto, onde está o objetivo, as funcionalidades e os requisitos gerais. O detalhe fino vai sendo acrescentado depois, com a ajuda da equipe funcional e de desenvolvimento.

Faço isso para o projeto poder avançar enquanto eu detalho as solicitações menos prioritárias. Esperar o escopo perfeito antes de começar é como esperar o mapa completo antes de sair de casa.

Quando o escopo é totalmente conhecido, esse documento fica bem especificado e às vezes dispensa documento de apoio. O que costuma acontecer, na verdade, é ele não ficar completamente detalhado: por inabilidade técnica de quem elaborou, por não conhecer o projeto inteiro, ou pelas mudanças habituais de qualquer projeto.

A seção que eu passei a considerar a mais importante, e que faltava nos meus próprios modelos: o que não está no escopo. Escopo se define excluindo. A lista do que não será feito é o que evita a conversa de "mas eu achei que estava incluso" no meio da execução.

Declaração funcional

Pode ser entendida como o documento de funcionalidades. Aqui os requisitos são especificados em detalhe: requisitos funcionais, não funcionais, regras de negócio.

Em alguns projetos ela não é desenvolvida, porque é um documento parecido com a declaração de escopo. Fica a critério da equipe. Normalmente ela é criada quando é preciso detalhar ainda mais o que a declaração de escopo definiu por cima.

Pode ter tópicos variados: fluxos, processos, casos de uso. O objetivo é que ela resolva qualquer dúvida da equipe de desenvolvimento.

Uma coisa que eu acrescentaria a qualquer declaração funcional: dar identificador a cada requisito. Sem ID, o caderno de testes, o commit e a discussão de três meses depois não conseguem apontar para a mesma coisa. É por isso que "o requisito mudou" costuma virar discussão sem prova.

E a seção que separa documento honesto de documento que parece completo: as pendências e dúvidas abertas, com dono e prazo. Pendência registrada é risco gerenciado. Pendência não registrada é surpresa.

Documentação técnica

Desenvolvida pela equipe técnica, aprofunda a nível de desenvolvimento o que os documentos funcionais e de escopo definiram.

O intuito é evidenciar o que precisa ser feito tecnicamente. Costuma conter diagrama de classes, diagrama de banco de dados, linguagens, arquitetura adotada, configuração de servidores de aplicação e de banco.

Esse é um dos documentos mais importantes do projeto, e existe um teste simples para saber se ele está bom. Não é se descreve tudo. É se, com ele em mãos, qualquer equipe capaz consegue dar prosseguimento ao projeto, mesmo que ninguém do time original esteja mais lá.

Ele também serve de base para o documento operacional.

Duas seções que eu acrescentei aos meus modelos e que mudam o valor dele a longo prazo.

Decisões de arquitetura, com as alternativas que foram descartadas e o motivo da escolha. Sem isso, a próxima equipe desfaz por ignorância uma decisão que existia por um bom motivo.

Dívida técnica conhecida. O que está errado e você sabe. Registrar não é confissão, é transferência de contexto: a próxima pessoa vai descobrir de qualquer forma, e descobrir sozinha custa semanas.

Um cuidado que eu aprendi da forma difícil: esse documento circula por e-mail, fica em pasta compartilhada e é anexado em chamado. Senha, chave e token não entram nele. E vale pensar duas vezes antes de copiar IP interno, hostname e porta para dentro dele: se existe inventário oficial, melhor referenciar, porque documento copiado envelhece e vira mapa desatualizado da rede.

Caderno de testes

Documento desenvolvido para auxiliar quem vai testar a ferramenta. É preparado quando a equipe de desenvolvimento finaliza a atividade e coloca em teste, e normalmente quem escreve são os próprios testadores.

Nele deve estar o fluxo da funcionalidade, e vale usar imagem, processo e detalhar cada clique. O testador dá o seu de acordo, aprovado ou reprovado, e é criada uma opção para o usuário final dar o dele também. Se outras pessoas realizarem o teste, entram no documento.

Esses "de acordo" validam que as funcionalidades foram testadas e registram quem foi responsável.

E aqui está a parte que dá peso ao documento: quem dá o aceite assume a validação. Se houver inconsistência no que foi testado, a responsabilidade é de quem testou. E depois da validação, alteração entra como nova demanda e segue o fluxo de novo desenvolvimento.

Por isso a coluna de quem testou não é burocracia. É ela que torna o aceite rastreável.

Uma mudança de formato que eu fiz nos meus modelos: esse documento deixou de ser texto e virou planilha. Caderno de teste é uma lista de casos com status, e em documento de texto não dá para filtrar por status, contar quantos passaram nem ordenar por prioridade, que é exatamente o que se faz numa homologação.

Manual do usuário

É um dos documentos mais trabalhosos para a equipe e o mais desvalorizado por quem recebe. Pense na última vez que você leu o manual do seu celular ou do seu carro.

Precisa ser bem detalhado, ensina a usar a ferramenta, e está constantemente sendo atualizado a cada funcionalidade nova. Normalmente é criado depois dos testes.

Costuma ter bastante imagem, para ajudar na visualização. E em software isso tem ganhado forma: os manuais estão virando tutorial interativo dentro da própria ferramenta, que aparece a cada funcionalidade nova. Essa prática é essencial para ganhar aderência, porque a ajuda aparece no momento da dúvida.

Mesmo sem tutorial programático, dá para criar manual que engaja. Apresentação bem feita permite algo bem mais dinâmico que documento de texto corrido.

A seção que eu passei a considerar a mais importante, e que quase nunca existe: o que costuma dar errado. É a única parte que a pessoa realmente procura, porque ela só abre o manual quando algo não funcionou como esperava. Escreva o texto exato da mensagem de erro, que é assim que ela encontra a resposta.

E organize por tarefa, não por tela. "Registrar um problema" funciona melhor que "tela de cadastro".

Documento operacional

Desenvolvido para fazer a passagem de conhecimento da equipe que construiu o software para a equipe que vai operacionalizar. Atende tanto o suporte quanto os administradores da ferramenta, aqueles responsáveis por criar usuário, fazer perfilhamento e alterar parâmetro.

A equipe de suporte já é voltada para problema e incidente. Então o documento precisa mostrar a arquitetura, onde estão os fontes, informação de servidor, banco e acesso. Credencial vai em arquivo separado ou em sistema seguro, nunca no corpo do documento.

Depois de preenchido, normalmente é necessária uma reunião com a equipe de suporte para a passagem e para tirar dúvidas.

Esse documento é aprovado pela equipe de suporte, e pode sofrer alteração conforme ela solicitar. E isso é legítimo: é ela que vai depender disso de madrugada.

Três seções que eu acrescentei porque são o que a sustentação pergunta na primeira semana.

Incidentes conhecidos e como resolver, com sintoma, causa provável e tratativa. É a seção que a sustentação mais usa e a que quase nunca vem preenchida.

Escalonamento com horário. Lista de contato sem horário de disponibilidade não serve de madrugada.

Backup com a data da última restauração testada. Backup nunca restaurado é hipótese, não é backup.

Os modelos

Refiz os seis documentos deste artigo e deixei disponíveis na Biblioteca, de graça e sem cadastro. Eles são guias para ajudar na elaboração: cada seção traz uma instrução do que escrever ali e um exemplo preenchido.

Baixar os modelos na Biblioteca

Se você está contratando fornecedor, o processo anterior a esses documentos está no artigo sobre RFI, RFP e RFQ.

E a pergunta que eu deixaria: no seu último projeto, se a pessoa que escreveu a documentação técnica saísse amanhã, o sistema continuaria evoluindo?