Fazendo um projeto dar certo: A Importância de Documentar o Projeto e o Sistema [250 posts no ar]

Se você está lendo esse post, significa que eu já publiquei 250 posts! #UAU

Os blogs têm me dado bastante trabalho. Estou gastando em média 8 horas com cada post inédito. Ultimamente, a audiência caiu bastante e a motivação foi junto. Mas sigo aqui escrevendo. Pra mim, pra alguém que goste ou até mesmo pra deixar como um documento histórico.

Ainda tenho ideias, ainda tenho a meta de escrever 90 posts inéditos em 2017 e escrever me realiza demais. Quando eu publico um post que ficou tão completo quanto eu imaginei, é uma sensação muito boa.

Hoje vamos visitar diversos documentos importantes durante a vida de um projeto e de um sistema.

Dependendo do orçamento do projeto e das características da equipe e do projeto, esses documentos podem variar bastante em seu grau de formalismo bem como nas ferramentas utilizadas para a geração dos mesmos. Também podem ser aproveitados templates (modelos) padronizados de documentos para garantir completude e produtividade.

Espalhadas no livro Fazendo um Projeto Dar Certo estão dezenas de dicas sobre a importância de documentar bem o projeto e o sistema.

> Leia agora a amostra gratuita de Fazendo um Projeto Dar Certo

Documentos em Projetos

O documento zero de um projeto talvez seja o contrato entre a empresa executora e a empresa demandante. É um documento de formalismo máximo porque dará o embasamento jurídico para todo o relacionamento entre as partes: cliente e fornecedor. É nessa hora também que serão conhecidas as pessoas físicas que se relacionarão no projeto representando as pessoas jurídicas envolvidas.

O Termo de Abertura do Projeto é o documento que formaliza a existência do projeto. A sua principal função é apresentar e dar a autoridade necessária à equipe de gestão do projeto para que esta possa começar a fazer o projeto acontecer.

A Declaração de Escopo é uma espécie de contrato só que com a ótica mais voltada ao gerenciamento de projetos. Ela descreve todo o trabalho (escopo) que deverá ser realizado no projeto e, não menos importante, o que não deverá ser realizado (não-escopo). É um alinhamento de expectativas crucial entre todas as partes interessadas.

O Cronograma é um documento que mostra o projeto sob uma ótica temporal. Ele mostra quando deverão ocorrer os principais eventos e entregas do projeto. Posso falar com muita experiência que esse é um dos documentos mais difíceis de se produzir e de se manter atualizado ao longo do projeto. :P

O Mapa de Riscos analisa as principais incertezas que podem afetar o sucesso do projeto bem como prevê possíveis estratégias de respostas aos eventos inesperados, sejam estes bons ou ruins. Esse planejamento prévio, antes que a desgraça aconteça, pode fazer toda a diferença para o projeto dar certo.

O Plano de Comunicação é uma espécie de metadocumento porque ele descreve quais informações devem ser produzidas pelo projeto, para quem estas devem ser distribuídas e em qual periodicidade.

O documento de Lições Aprendidas é um registro formal da reflexão da equipe sobre os erros e acertos cometidos ao longo da execução do projeto. É um conhecimento extremamente útil para as futuras fases do projeto, para futuros projetos bem como para outras equipes.

Os relatórios de acompanhamento (status report) são elaborados ao longo do projeto para que todas as partes interessadas possam ficar atualizadas sobre o que está acontecendo, sobre o que não está acontecendo, sucessos e fracassos, enfim, sobre o quanto o projeto está seguindo o plano estipulado.

O Termo de Encerramento é o documento que formaliza a finalização das atividades do projeto. Pense no fim de um namoro e que é necessário deixar isso bem claro para as duas partes. :P

Documentos em Sistemas

Documentar um sistema custa muito caro e, na visão de alguns, não gera nada “útil” para o cliente. “Papéis não compilam” hehe

Se é caro gerar a documentação inicial, manter essa documentação viva, atualizada, útil e confiável também é caro.

E de que adiantam 10 gigas de documentos desatualizados e que a equipe simplesmente os descartam por não confiar plenamente neles?

Manter um sistema sem documentação depende única e exclusivamente dos analistas que construíram esse sistema. E aí não tem mágica: eles detêm o conhecimento em suas cabeças e a empresa proprietária do software é refém desses profissionais.

Para muitos, o código também é a documentação do sistema. Um código legível e bem organizado ajuda a entender mais facilmente como o sistema funciona e barateia as futuras manutenções. Mas não se iluda: o cliente nunca vai ler código.

Os protótipos são documentos intermediários que ajudam a vislumbrar a aparência esperada do sistema.

Os requisitos definem o que o sistema deve apresentar quando estiver pronto. As regras, por sua vez, definem como o sistema se comporta (regras de negócio) e quais são as entradas aceitas (regras de validação). Esse combo de requisitos e regras é a documentação básica do que é possível se fazer com o sistema.

Os casos de uso são documentos que descrevem a usabilidade do sistema, narrando a utilização do sistema por um usuário. Para cada ação possível do usuário, qual resposta o sistema deve apresentar.

Muita gente critica os casos de uso por serem documentos de difícil leitura o que acaba os tornando menos úteis.

Os casos de testes são uma espécie de documentação “de trás pra frente”. Supondo-se o sistema pronto, o caso de teste valida se o resultado produzido (gerado) é condizente com o resultado previamente esperado.

As histórias de usuário e os seus cenários de testes são alternativas menos verbosas aos casos de uso e casos de testes. Obviamente, geram uma documentação menos completa. É o velho dilema do custo-benefício.

Um documento muito importante para um sistema é o manual do usuário. Basicamente, ele descreve para os usuários finais como o sistema pode ser utilizado com segurança e em sua plenitude. E aqui perceba que o manual pode se apresentar em forma de tutorial ou de videoaula.

Fotos Antigas das Metrópoles

Há alguns meses, incrementaram a decoração do hall de entrada do prédio onde eu trabalho com fotos bastante antigas de Fortaleza. Eu achei genial. É histórico e reconfortante. A nossa imaginação viaja tentando fazer o link entre a imagem de hoje e a imagem do passado.

E foi de lá que eu tirei o mote para fazer esse post que ficou incubado por vários meses.

Uma foto é um documento riquíssimo que congela uma determinada imagem de um determinado momento.

A partir daqui, na parte lúdica do post, algumas fotos antigas de algumas das maiores cidades do Brasil…