• Distinguer la documentation conceptuelle (why-doc) de la documentation pratique (how-doc)
• La documentation conceptuelle (why-doc) a rarement besoin de changement. Celle-ci a toujours sa place dans un wiki ou README
• La documentation pratique (how-doc) a un cycle de vie beaucoup plus court. Elle est composée de snippets immutables d'une ligne qui peuvent être ajoutés et recherchés via un bot Slack.

L'utilisation de Slack a ici plusieurs intérêts:

• Chaque snippet est timestampé et relié a un auteur
• Les snippets sont triés par ordre chronologique du plus récent (Doc la plus fraîche) au plus ancien (potentiellement obsolète)
• L'ajout de snippet est directement intégré au système de communication qui sers aux questions/réponses, quand on pose une question sur Slack, le coût pour ajouter la réponse dans la doc est donc quasi-nul
• En revanche si l'on souhaite se passer de Slack ou d'un équivalent, on pourrait très facilement développer un script permettant d'ajouter/rechercher des snippet timestampés dans un backend (simple fichier versionné, service rest très simple, bdd SQLite) en s'inspirant de certains outils de gestion de todo-list en ligne de commande par example

Quelques conseils pour écrire la documentation minimale d'un projet git (README, CHANGELOG, commentaires)

terraform-docs génère une doc au format markdown ou json à partir des templates terraform