O que deve ficar documentado num projeto tecnológico

O que a empresa tem de conseguir recuperar quando a equipa ou o fornecedor mudam

Num projeto tecnológico, devem ficar documentadas as decisões, as responsabilidades, as ligações entre sistemas, as configurações essenciais e os procedimentos de operação. Com esta informação, a empresa consegue compreender e alterar o que foi desenvolvido, mesmo quando a equipa ou o fornecedor muda.

Sem esse registo, qualquer mudança, planeada ou inesperada, como a saída de um colaborador, o fim de um contrato ou a reorganização da equipa, implica perder conhecimento essencial e transforma-se num problema de continuidade operacional. A empresa só descobre o que falta no momento em que precisa da informação, geralmente perante uma falha ou uma alteração urgente.

Que informação vale o esforço de registar

O ponto de partida são as decisões e os respetivos motivos. Saber que uma integração envia dados num único sentido é útil, mas saber porquê, por exemplo, para evitar alterações em dois sítios, impede que alguém a modifique mais tarde sem perceber o que está em causa. A isto juntam-se as responsabilidades e os contactos de referência: quem validou a decisão, quem responde por cada sistema, por cada tipo de dado e por cada aprovação, e a quem recorrer se for necessário alterá-la. A distribuição de responsabilidades entre plataformas foi desenvolvida no artigo sobre como definir o papel de cada sistema na operação da empresa.

Para as integrações, interessa registar que dados circulam, em que sentido e com que frequência, de modo a que a empresa saiba o que depende de quê, tema que abordámos no artigo sobre como escolher a forma de integrar sistemas empresariais. Quanto às configurações, aos ambientes e aos acessos, a empresa deve saber onde estão alojados os sistemas, que contas existem, quem as gere e qual é o procedimento autorizado para recuperar o acesso. Isto evita que a empresa perca o controlo de um sistema quando muda a pessoa que o geria. Documentar acessos não é registar palavras-passe nem reuni-las num documento: as credenciais devem continuar protegidas por mecanismos apropriados, controlados pela empresa.

Por fim, os procedimentos de operação, manutenção e recuperação: como se reinicia um processo que falhou, como se corrige um registo, quem contactar e o que fazer quando a ligação entre dois sistemas deixa de funcionar. No software à medida, é útil separar duas coisas. Importa definir desde o início que documentação técnica será necessária para operar, manter e evoluir a solução, bem como as condições em que será disponibilizada ao cliente. Já o direito de aceder ao código-fonte, de o utilizar ou de o modificar depende das condições contratuais acordadas com o fornecedor, e não é garantido pelo simples facto de o software ter sido desenvolvido à medida.

Um exemplo: a integração que só uma pessoa conhecia

Imagine-se uma empresa em que a integração entre o CRM e o sistema de faturação foi montada por um fornecedor externo há dois anos e acompanhada, desde então, por um único colaborador. Quando esse colaborador sai, surgem perguntas simples sem resposta: por que é que a morada só é atualizada num sentido, o que acontece quando a sincronização falha durante a noite, quem é responsável pela gestão da conta do serviço de alojamento. A empresa tem de reconstruir as respostas a partir do comportamento dos sistemas, com o risco de alterar algo que estava assim por uma razão. Em integrações antigas, ou que dependem de serviços externos aos quais ninguém tem acesso, essa reconstrução pode ser complexa e exigir tempo, testes e intervenção técnica.

Uma página de documentação por integração, que registe o objetivo, o sentido dos dados, a frequência, o responsável, o que fazer em caso de falha e onde estão as contas, é um ponto de partida que tornaria a mesma saída numa passagem de testemunho e não numa investigação. Não basta em todos os projetos: nas integrações mais complexas, deve ser complementada por documentação técnica.

Quem mantém a documentação e quando se atualiza

Há duas funções distintas. Alguém na empresa deve ser responsável por garantir que a documentação existe, está completa para os sistemas críticos e é acessível a quem precisa dela. Quem a atualiza no dia a dia depende do projeto: pode ser a equipa interna, o fornecedor ou ambos, e essa divisão deve ficar definida desde o início. Sempre que existe uma alteração relevante, quem a executa deve assegurar que a documentação correspondente é revista, de acordo com as responsabilidades estabelecidas.

As alterações a integrações, a perfis de acesso ou a procedimentos críticos registam-se quando acontecem. A revisão periódica, por exemplo, anual, serve para detetar informação desatualizada e não substitui essa atualização contínua. O mesmo vale para as decisões: registam-se quando são tomadas, porque os motivos esquecem-se depressa e, no fim do projeto, ficam apenas os resultados. Uma nota curta, com a data, a decisão e o motivo, escrita na altura, vale mais do que um documento extenso elaborado meses depois.

O local também conta, pois se a documentação existe apenas nos sistemas do fornecedor ou no computador de um colaborador, perde-se precisamente com a mudança que se pretendia prevenir. Deve estar num espaço controlado pela empresa e acessível a quem precisa dela.

O que não precisa de ser documentado

Documentar não significa reproduzir informação que já está disponível, atualizada e acessível numa fonte fiável. Os registos de acessos e de alterações gerados automaticamente pelos sistemas, por exemplo, não precisam de ser transcritos, embora possa ser necessário documentar onde se encontram, como se consultam e quem tem acesso a eles. A distinção entre estes registos e a documentação do projeto foi explicada no artigo sobre transformação digital em setores regulados.

O que importa documentar são as decisões, as regras de negócio, os comportamentos específicos e os procedimentos de exceção, ou seja, aquilo que não se compreende apenas pela utilização do sistema. A profundidade deve acompanhar a criticidade: um sistema de que depende a faturação merece mais detalhe do que uma ferramenta de apoio usada por uma só pessoa.

Documentar para poder mudar

Um ponto de partida realista é escolher os dois ou três sistemas ou integrações mais críticos e preparar, para cada um, um resumo que outra pessoa consiga usar. Isto permite identificar o conhecimento que ainda depende de determinadas pessoas e reduz o impacto de futuras mudanças.

Um teste simples ajuda a avaliar o resultado: pedir a alguém que não participou no projeto que explique como o sistema funciona e como se recupera de uma falha, apenas com base na documentação. As perguntas que essa pessoa não conseguir responder revelam o que ainda precisa de ficar documentado. É assim que a documentação cumpre a sua função: permitir que a empresa mantenha e altere os seus sistemas sem depender exclusivamente da memória ou da disponibilidade de determinadas pessoas.