Doc As Code

La documentation technique d’un projet logiciel est souvent un sujet délicat au sein des projets.

Soit il n’y en a pas du tout et le savoir est présent uniquement “dans la tête” des développeurs, soit il y en a partout… des commentaires, des documents textes, un wiki et, malheureusement, cette documentation n’est pas à jour…

Comment améliorer ces situations que nous rencontrons bien trop souvent ?

Une solution possible est de traiter la documentation comme du code !

C’est ce que je vous invite à (re) découvrir dans cette conférence où nous parlerons des bonnes pratiques de documentation, ainsi que des outils pouvant nous aider à répondre aux besoins de rédaction et de maintenance d’une documentation.

Basé sur un retour d’expérience d’usage de ces méthodes et outils depuis une dizaine d’années en milieu professionnel, je vous propose d’aborder :

• Les formats (README, Architecture Decision Records, Wiki, …),
• Les outils (NDoc, OpenAPI, Markdown, Mermaid, DocFX, Obsidian, …),
• Le cycle de vie de la documentation (fréquence de mise à jour, “distance” entre le code et la doc, maintenance, …),
• La génération d’un site de documentation à partir de votre chaîne d’intégration continue.

Cette conférence sera illustrée par des exemples au travers d’un live coding en .Net / C# et nous terminerons par une session de questions/réponses afin de partager d’autres retours d’expérience ou de creuser certains sujets plus en détail.