O que usar para criar documentação do meu produto?
Olá pessoas, tudo bem com vcs? Atualmente onde eu trabalho não temos documentação do nosso produto, estavamos em busca de algo como o NOTION ou derivados para fazer documentação de tudo que temos no banco ou de bibliotecas que usamos internas etc. Gostaria saber se vocês conhecem algum produto gratuito que possa ser usado internamente não precisando usar o serviço de terceiros como o Notion que se um dia "cair" não podemos acessar a documentação. Não sei se fui claro no que eu quis perguntar e peço desculpas se não fui, mas eu gostaria dessa ajuda de Devs mais experientes não só para a empresa como pra mim também, que tenho vontade de documentar meus projetos. Já agradeço a atenção de todos ai abraçossss
Eu sou bem minimalista com documentação, como diz o Agile manifesto "working software over extensive documentation".
Em geral boa nomenclatura no software (vide capítulo meaningful names do clean code), diagramas de classe e sequência uml e um documento markdown.
Tudo isso cabe no mesmo repositorio git, no README.md é possível embarcar os diagramas usando MermaidUML no github.
Independente da ferramenta que você vai usar para fazer a documentação, é interessante pensar em como organizar a documentação. Para isso o Diátaxis é um excelente ponto de partida. Ele é um método de organizar documentação, dividindo-a em quatro categoria: tutoriais, guias, referência e explanação. Recomendo muito.
Sobre as ferramentas, para começar, eu faria bem simples:
- Documentar o código usando ferramentas próprias da linguagem ou de amplo uso da comunidade. Por exemplo: Docstrings para Python, JSDoc para JavaScript, JavaDoc para Java, etc. Essas ferramentas leem os comentários adicionados no código e geram a documentação.
- Documentar como é a arquitetura do sistema, alguns tutoriais, etc., usando alguns arquivos .md no próprio repositório do projeto. Com o tempo a necessidade de usar uma ferramenta de documentação mais robusta, como o Sphinx, vai surgir, mas a complexidade de implantar isso de cara pode tirar o ânimo de começar a documentar.
- Colocar as pessoas para usar a documentação. A documentação serve para economizar o tempo de alguém explicando pra outra pessoa o que deve ser feito. Então coloque o novato para tentar por o projeto pra funcionar usando só a documentação disponível. Isso vai deixar claro o que deve ser melhorado para que o próximo novato tenha mais autonomia em usar o projeto.