doctoolchain: SW Dokumenation mit Markup

doctoolchain

Mit großem Interesse habei ich mir die doctoolchain angesehen. Da der Autor hier einen großen Overlap zu meinen eigenen aktuellen Standpunkt und Tooling erkennen lässt (versioning, plain markup/asciidoc, gradle, arc-24, living documentation) lässt sich doch einiges aus dem Toolset lernen, als Idee herausziehen oder direkt verwenden.

Highlights bei denen ich mich bei Bedarf bedienen werde:

  • export aus excel (für Protokolle und Konfigurationsmatrix)

  • plantuml ohne dot (plain java)

Tolle Sachen die ich aber nicht übernehmen kann

  • jira export.. das bräuchte ich für gitlab und/oder tfs für meine Projekte. Das kann man analog lösen, müsste ich aber halt selber angehen.

  • Powerpoint/Visio export.. das braucht leider Powerpoint/Visio installiert, was für meine verwendete CI systeme (meist docker/linux basiert) den Aufwand nicht Wert ist. Aber natürlich bleibt auch für mich das Thema "wie Grafiken abseits plantuml nutzen" weiter ein Thema.

Caution
Ein freies Diagramm-Tool (a la Visio, Powerpoint, Presenter) mit gradle fähigem image-export/rendering und vielleicht sogar mit git freundlichem (text) Dateiformat wäre ein Traum. Anyone to the rescue ???

Was ich anders sehe/mache

  • Die Dokumente werden hier einzeln konfiguriert (zumindest default)

Das finde ich für viele Typen von Dateien unnötig (z.B. für Protokolle).

  • Es fehlt für mich das Zusammenbinden von Einzeldokumenten zu einer Gesamtdokumentation (was ich dann über jbake mache)

Mit jbake (oder Hugo oder was auch immer) kann man Übersichtsdokumente, Inhaltsverzeichnisse, Themenbasierte Listen etc. Generieren und muss das nicht per Hand mitpflegen.

So muss man also nicht wie bei doctoolchain ein neues Protokoll einmal in Config.groovy zur Generierung eintragen und dann nochmal 1..n mal in Inhaltsvereichnisse oder Übersichten eintragen.

Published by in documentation and tagged documentation, markup and qa using 261 words.