HOME
Blog Datenschutz Impressum
Blog Datenschutz Impressum

DotNet

Quellcode-Dokumentation mit DocFX und Mermaid.js

Erstellt in DotNet am 25.04.2020

Zu Zeiten von Markdown und gezielter Quellcode Dokumentation wird es immer wichtiger auch Bilder in seinen Beschreibungen zu hinterlegen. Ablauf-, Zustands oder Fluss-Diagramme können sehr hilfreich bei der Erklärung vorhandener Strukturen oder getroffene Entscheidungen sein. Leider sind Strukturen und Entscheidungen in unserer agilen Welt sehr flüchtig und unterliegen einer stetigen Änderung.

Jeder Entwickler kennt wahrscheinlich das schlechte Gefühl eine Grafik für seine aufwendig entworfene Dokumentation in irgeneinem Grafik-Programm zu entwerfen und diese dann als Binär- oder XML-, bzw JSON-Datei im Quellcode Repository einzuchecken. Eine Änderungshistorie ist dann eigentlich nur noch über den Kommentar des Commits gegeben. Alle Team-Mitglieder müssen dann ebenfalls das Grafik-Programm, möglichst in der gleichen Version, installiert haben und in dem verwendeten Grafik-Programm geschult sein.

Eine mögliche Lösung ist der Einsatz von DocFX und Mermaid.js. Dabei dienst DocFX als Quellcode-Dokumentations-Generator und Mermaid.js als Dialekt zum Beschreiben von Diagrammen und Charts.