Executando verificação de segurança...
1

Como vocês documentam um software?

Neste momento estou arrancando meus cabelos para escrever uma documentação de um software que minimamente foi modelado.

O dilema basicamente é que um cliente X me pediu o desenvolvimento de uma plataforma web e justamente agora no momento da entrega ele me pede também uma documentação, mas sem especificar qual.

E como Dev iniciante eu não tenho a minima ideia de qual a melhor forma de documentar. O que conheço é UML e documento de arquitetura de software, mas agora que o projeto está pronto - e obviamente com muita gambiarra - não consigo adequar o que está pronto com uma documentação que deveria ser feita na modelagem do projeto.

O que vocês fariam ? Que tipo de documento escreveriam ?

Carregando publicação patrocinada...
1

Brother, vou partir do princípio que o "Dev iniciante" a que você se refere é porque deve ser um dos primeiros trabalhos que você faz. Até porque, se fosse Dev Junior, provavelmente você teria supervisão e poderia questionar diretamente a equipe.

Se o cliente não especificou, acho que você deveria perguntar, uma vez que o cliente tem uma expectativa, e acho o alinhamento de expectativas importante tanto para você quanto para o cliente. Além disso, ainda vai ajudar a evitar frustrações de ambos. No entanto, acredito que você pode ter umas pistas, por exemplo, em outros projetos que esse mesmo cliente já recebeu de outros programadores, ou se você conversou com o cliente no início da contratação e mostrou alguma coisa minimamente documentada, você pode fazer o que já sabe. Logo, respondendo à primeira pergunta, o que eu faria é perguntar ao cliente, mesmo eu avaliando todo o contexto, pois o cliente está pagando.

Em relação ao tipo de documento, acho que é mais uma autoanálise dos desafios técnicos que você teve. Uma coisa que você tem que ter em mente é que, futuramente, você pode ter que dar manutenção no sistema. Logo, um documento com os pontos que você acha importante já é um bom começo. Mas, se você pensar de uma forma parecida com a minha, documentaria para você e para outros programadores, o que, na minha opinião, é o estado da arte da documentação, ou seja, aquela documentação que tem empatia com quem vai ler ela futuramente.

1

Como o Felipe Chirmann comentou o ideal seria nesse primeiro momento conversar com o cliente para entender o que ele quer.

Eu sou dev backend então normalmente eu uso o https://swagger.io/ para gerar a documentação da API. Você pode usar a documentação do Brasil API como referência https://brasilapi.com.br/docs

Se você também fez o front também você pode usar o Google Docs e criar um documento compartilhado com o cliente. Nesse documento você pode listar os casos de usos, explicar as principais validações, quais dados são alimentados ou impactados por essa rotina.
Citando um exempo para ilustar melhor, vamos dizer que você tem um módulo financeiro e tem uma rotina de cadastro de contas a pagar. Na seção Módulo FInanceiro do documento você coloca, rotina de contas a pagar e descreve como ela funciona, coloca um foto da tela, lista as validações, ex, não pode cadastrar conta com data inferior a data atual. Você também pode comentar as rotas da API que são consumidas por essa rotina e por aí vai. Essa documentação pode ser bem extensa, por isso é importante alinhar com o cliente e verificar o que foi acordado no momento da contração, afinal são horas e horas de trabalho.

E por fim tem a documentação do código em si, existem N ferramentas no mercado para cada linguagem, mas de uma forma bem geral, você usa um padrão de comentário e o programa gera a documentação com base nele. Eu não uso nenhuma ferramenta desse tipo, mas olhando por cima aqui no Google eu achei esse artigo https://userguiding.com/pt-br/blog/ferramentas-documentacao-software/