Grenzen der automatischen Dokumentation

Doxygen etc. erzeugen nicht wirklich automatisch Dokumentationen. Sie restrukturieren und formatieren Informationen, die von Hand geschrieben wurden, entweder in Form von Code (der eine Form strukturierter Daten ist) oder in den Code geschriebene Kommentare. Sie formatieren und veröffentlichen die Informationen automatisch. Sie generieren Inhalte nicht automatisch.

Für mich besteht die auffälligste Einschränkung dieser Tools darin, dass sie eine separate Veröffentlichungs-Toolkette darstellen, die nichts mit der Toolkette zu tun hat, die für den Rest des Dokumentationssatzes verwendet wird. Das bedeutet zunächst einmal, dass Sie die gesamte Arbeit der Konfiguration und Pflege der Toolchain sowie der Präsentation und Formatierung Ihrer Inhalte zweimal erledigen müssen. Und weil diese alle über relativ grobe Publishing-Engines verfügen, können Sie ihre Ausgabe oft nicht wirklich an das Design des restlichen Dokumentationssatzes anpassen.

Das zweite Problem dabei ist, dass es keine Integration zwischen den von ihnen produzierten Inhalten und dem Rest Ihrer Inhalte gibt. In den Tagen der Zeitung war dies weniger ein Problem, aber jetzt, da wir hauptsächlich im Web veröffentlichen, macht es es schwieriger, elementare Dinge zu tun, wie das Generieren von Links von Erwähnungen einer Funktion im Programmierhandbuch zur Auflistung dieser Funktion in die API-Referenz.

Die Lösung für diese Probleme besteht darin, die XML-Ausgabe dieser Tools in die allgemeine Toolkette einzuspeisen. Dies setzt natürlich voraus, dass Ihre allgemeine Toolkette XML-basiert ist oder zumindest in der Lage ist, einen XML-Feed zu empfangen und einzubinden. Dies ist bei den meisten handelsüblichen Schreib- und Veröffentlichungstools nicht der Fall. Das Ergebnis ist, dass Ihre API-Dokumente als Insel verbleiben.

Automatisierte Systeme wie Sandcastle und Swagger sind gut darin, Codesyntax in Dokumentation umzuwandeln. Diese werden eine Randdokumentation erstellen. Was sie nicht tun, ist, Einblicke in die Anrufe hinzuzufügen. Selten existiert eine Methode für sich allein. Es werden immer zusätzliche Anmerkungen benötigt, Vorbehalte erklärt, Nebenwirkungen, Klarstellungen für jeden Parameter, Rückgabewerte, die Methode selbst und sogar die Verwendung der Methode in einem größeren Kontext. Vergleichen Sie beispielsweise eine typische MSDN-Referenzseite mit einer beliebigen REST-Referenzseite. Für jede Methode ist die MSDN-Seite länger und detaillierter, wie sich die Materialentwickler wünschen. Die REST sind in der Regel knapp mit weniger zusätzlichen Noten.

Dann gibt es Beispiele und Codeschnipsel. Keine automatisch generierte Anwendung kann diese erstellen. Viele Leute verstehen die API-Dokumentation nicht. In 95 % der Fälle möchten Entwickler nur ein Beispiel zum Kopieren und Einfügen. Die automatisierte Dokumentation erzeugt diese selten.

Viele denken, dass es ausreicht, eine Referenzseite verwenden zu können. Es ist nicht. Es ist die Leichtigkeit und Vollständigkeit bei der Beantwortung der Fragen, die zählt. Das ist der Unterschied zwischen angemessener Dokumentation und großartiger Dokumentation.