Documentação perto do código

Eu encorajo e me arrisco a seguir os seguintes princípios:

• O código é mais importante do que a documentação, mas com o tempo você vai esquecer parte do que codificou. Portanto, documente desde o início para obter uma visão de alto nível do que você fez.

• O código é mais importante do que a documentação, mas ter a documentação ajudará qualquer pessoa a ingressar no projeto no futuro. Isso evitará o fator ônibus.

• Usar uma ferramenta de documentação específica é legal, mas se estiver muito longe do código, você pode esquecer de atualizar a documentação. Portanto, traga a documentação o mais próximo possível do código.

---

Tópico 2 do Manifesto Ágil: "Software em funcionamento mais do que documentação abrangente."

Vamos procurar melhores formas de integrar o código à documentação. Software funcional é importante, mas ainda precisamos de documentação.

---

Exemplos de ações que promovem direta ou indiretamente a documentação próxima ao código:

• Plantuml (https://plantuml.com);
• Swagger (https://swagger.io);
• Markdown (https://www.markdownguide.org)

Feedbacks são sempre bem-vindos.

Repositório do Github: https://github.com/savi8sant8s/documentation-near-the-code