Mit meinem open-Source-Projekt DataHandwerk-toolkit-mssql möchte ich auch Erfahrungen zur Dokumentation zukünftiger Projekte sammeln. Warum habe ich mich für die Auszeichnungssprache AsciiDoc statt für Markdown, und warum für das Dokumentations-Framework Antora entschieden? Wie wurden Diagramme in der Architektur-Beschreibung erstellt? Und wie erfolgt die Darstellung von Objekt- und Spalten-Referenzen?
Auszeichungssprache Markdown?
Sehr oft erfolgt die Dokumentation unter Verwendung der Auszeichungssprache Markdown, Markdown Wikipedia
-
in den mir bekannten Wiki-Systemen wird mit Markdown gearbeitet (manchmal auch zusätzlich mit weiteren Auszeichungssprachen)
-
Es gibt viel und gute Software-Unterstützung für Markdown
-
Am PC verwende ich Visual Studio Code zum Editieren und zur Vorschau von Markdown. Und es gibt genügend andere Möglichkeiten, mit Markdown zu arbeiten
-
Auf Android verwende ich Markor, gelegentlich auch Epsilon Notes
-
-
Diese Website hier wird mit dem Generator für statische Seiten Jekyll erstellt und seine Inhalte sind in Markdown geschrieben
-
Meine Notizen schreibe ich in Markdown, womit auch ein sehr einfacher Austausch zwischen Smartphone und PC möglich ist. Die Notizen können auch mit jedem beliebigen Plain-Text-Editor gelesen und bearbeitet werden. Ich werde nicht zum Sklaven einer Notiz-Software.
-
Zur technischen Projektbeschreibung in Markdown gibt ein gutes open-source-Projekt: mkdocs.org. Darauf basierend gibt es Material for MkDocs
Doch Markdown hat auch entscheidende Schwächen:
-
alles muss in einem Dokument enthalten sein, es gibt kein "include", um Blöcke oder Inhalte aus anderen Dateien einzubinden
-
es gibt nicht "das eine Markdown", sondern Dutzende verschiedene Dialekte, wobei diese Dialekte teilweise auf unterschiedliche Art und Weise versuchen, Markdown um fehlende Funktionen zu ersetzen.
Hier kann man testen, wie Markdown von verschiedenen Dialekten unterschiedlich in HTML konvertiert wird: Test mit babelmark.github.io -
einen automatischen eingebauten TOC (Table of Content, Inhaltsverzeichnis) gibt es nicht, dieser muss separat erstellt werden (doch dafür gibt es Tools)
Auszeichnungssprache AsciiDoc!
Die GitHub Wiki hat Markdown Support, will oder kann aber nicht einen automatischen TOC erstellen. Doch GitHub Wiki und readme Dateien unterstützen nicht nur Markdown, sondern auch AsciiDoc. Und AsciiDoc kann den TOC "out of the box" erstellen. So fand ich zu AsciiDoc.
Und ich bin begeistert von den Möglichkeiten, die AsciiDoc im Vergleich zu Markdown bietet, wenn es darum geht, eine gut formatierte Dokumentation zu erstellen. Besonders wertvoll ist die Möglichkeit, auch Inhalte aus anderen Dokumenten als "includes" einzubinden. Variablen können verwendet werden. Es gibt eine Syntax, und nicht dutzende Dialekte. Dabei ist die Syntax ähnlich einfach, wie die von Markdown:
Allerdings werde ich für normale Notizen vorerst weiter Markdown verwenden müssen, wenn ich sowohl auf Android als auch am Rechner an diesen Dokumenten arbeiten will. Denn mein Android-Editor Markor hat leider noch keine AsciiDoc-Unterstützung implementiert: Add format: AsciiDoc (Highlighter, TextActions)
Und ich habe auch noch keinen anderen Android-AsciiDoc-Editor gefunden.
Update (2022-08):
obwohl es immer noch keinen Android Editor mit AsciiDoc Unterstützung gibt, habe ich mein Notizen-System von Markdown auf AsciiDoc umgestellt. Die Notizen befinden sich in einem privaten Repository auf Gitlab, es gibt für Android einen Git-Client MGit, als Editor verwende ich weiter Markor.
Update (2024-07):
Seit längerer Zeit enthält Markor auch eine eingebaute AsciiDoc Anzeige. Der Umweg über den lokalen Webserver ist nicht mehr nötig.
obsolete (2024-07):
der Preview erfolgt über einen lokalen Webserver, ich verwendete dazu den im Play Store nicht mehr verfügbaren NiM Webserver, aber es gibt andere Webserver. Die Anzeige erfolgt mit der Asciidoctor.js Live Preview im KiwiBrowser
Konfiguration Nim Webserver:
-
Es müssen neue
Mime Typehinzugefügt werden:-
.adocalstext/plain -
.mdalstext/plain(optional, wenn man auch gleich noch Markdown-Dateien anschauen will)
-
-
Die Sortierung der Dateien erfolgt unter Berücksichtigung von Groß- und Kleinschreibung, ob und wo man das ändern kann, weiß ich nicht.
Da man im Chrome Android keine Erweiterungen installieren kann, verwende ich dafür den KiwiBrowser. Auch einige andere Browser ermöglichen die Verwendung von Erweiterungen (Yandex,…).
Das scheint etwas kompliziert, muss aber nur einmal eingerichtet werden. Und AsciiDoc ist auch ohne Preview gut lesbar.
'Docs-as-Code' und 'Code-as-Docs'
Über AsciiDoc fand ich das Konzept "Docs-as-Code".
Docs-as-Code und AsciiDoc passen auch sehr gut zu meiner langjährigen Begeisterung für das, was ich Code-as-Docs nenne: die Dokumentation direkt aus dem Code oder unter Verwendung des Codes zu erstellen. Denn mit AsciiDoc kann man den Inhalt anderer Dokumente einbeziehen. Diese Inhalte können somit im Code (beispielsweise in Kommentaren) vorbereitet werden.
Ein Beispiel sieht man auf dieser Seite meiner DataHandwerk-Projekt-Dokumentation: Create, update and connect repository database
Hier werden
-
Text-Inhalte anderer Dokumente eingebunden und manchmal zitiert
-
die gleichen selben (!) in PlantUML definierten Diagramme verwendet, wie auch in den Architektur-Dokumenten
-
Am Ende des Dokuments wird der SQL Code einer Prozedur eingebunden. Wenn sich der Code ändert, kommen diese Änderungen auch in der Dokumentation an.
-
Eigenschaften wie eine Beschreibung oder ein Anwendungs-Beispiel der Prozedur können im Kommentar einer Prozedur definiert werden, um dann auf der Dokumenations-Seite der Prozedur zu erscheinen:
config.usp_connect_database
/*
<<property_start>>MS_Description
* connect repo datatabase to dwh database using synonyms executing
* see details in xref:manual:create-update-connect-repo-db.adoc[]
<<property_end>>
<<property_start>>exampleUsage
EXEC [config].[usp_connect_database]
@dwh_database_name = 'WideWorldImporters'
<<property_end>>
*/
CREATE Procedure [config].[usp_connect_database]
( @dwh_database_name NVarchar(128))
As
Begin
--
--ensure existence of required parameters like 'dwh_database_name'
Exec config.usp_init_parameter;
...docToolchain
docToolchain is an implementation of the docs-as-code approach for software architecture plus some additional automation. The basis of docToolchain is the philosophy that software documentation should be treated in the same way as code together with the arc42 template for software architecture.
Ich war begeistert, wie schnell sich docToolchain nicht nur installieren ließ, sondern dass auch sofort alles auf Anhieb funktionierte. Ein Kommando im Terminal, und kurz darauf war alles in schönstem HTML5 gerendert: Die Inhalte eingesammelt aus verschiedenen Dateien, Diagramme in PlantUML definiert. Man kann sogar Excel verwenden, um auch etwas kompliziertere Tabellen in Excel zu erstellen und für AsciiDoc zu exportieren (zur weiteren Verarbeitung durch AsciiDoc).
Einfach ist es auch, basierend auf dem Template github.com/docToolchain/arc42-template-project auf Knopfdruck eine fertige Mico-Site zu erstellen: arc42-demo.netlify.app Diese Idee gefiel mir so gut, dass ich ursprünglich damit auch meine Projekt- und Datenbank-Dokumentation erstellen wollte. Im Beispiel sieht das auch alles sehr schön aus, in der Praxis ist aber der TOC auf der linken Seite fest eingebaut und hat keine vertikale Scrollbar. So dass damit Inhalte am unteren Rand abgeschnitten werden und nicht erreichbar sind:
Leider habe ich nicht gefunden, wie man das im CSS (oder wo auch immer) ändern könnte oder müsste. Und irgendwann habe ich aufgegeben:
toc is static without scrollbars. long toc are hard to use. very different view in preview and on the website
Mit ein wenig mehr Energie lässt sich das vielleicht lösen.
Update: Inzwischen wird ein anderes Standard-Thema verwendet und das Problem wurde dadurch gelöst.
arc42
doctoolchain ist mit den Leuten von arc42 verbandelt.
arc42 enthält ein erprobtes und pragmatisches Template zur Entwicklung, Dokumentation und Kommunikation von Softwarearchitekturen. Tausende zufriedene Nutzer weltweit.
Also habe ich mir das angeschaut und für gut befunden. Das DataHandwerk-Architektur-Dokument basiert auf diesem Template: Architecture
Structurizr DSL und das C4 Modell für die Visualizierung von Software-Architektur
Meine ersten Architektur-Diagramme erstellte ich noch manuell und individuell mit PlantUML. Dann fand ich Structurizr und github.com/structurizr/cli, um Software Architektur Diagramme formalisierter zu erstellen. Die Definition erfolgt in einem Skript in einer eigenen und einfachen Skript-Sprache Structurizr DSL, und aus diesem einen Skript können verschiedene in sich konsistente Diagramme erstellt werden. Man ändert beispielsweise Beschreibungen oder Beziehungen im Skript und alle Teil-Diagramme übernehmen diese Änderungen.
Beispiele finden sich in der DataHandwerk-Architektur-Dokumentation: 03 System Scope and Context
Definition meiner Architektur-Diagramme in "Structurizr DSL": dhw.dsl
Antora
Nachdem ich es mit docToolchain nicht geschafft hatte, eine Website zur Projekt- und Datenbank-Dokumentation mit einem TOC zu erstellen, der meinen Vorstellungen entsprach, schaute ich mir Antora an, da dieses Werkzeug von den gleichen Entwicklern erstellt und gepflegt wird, die auch Asciidoctor entwickeln. Folgende Dokumentationen werden ebenfalls mit Antora erstellt und sie bieten das, was ich mir unter einer guten Dokumentation vorstelle. Und sie basieren ausschließlich auf meinem neuen Liebling AsciiDoc
Allerdings ist der Einstieg in Antora nicht ganz so einfach, wie der in doctoolchain: Die Quellen der Dokumentation müssen in einer bestimmten Struktur vorliegen und es werden nur Inhalte aus dieser Struktur verwendet. Ein großer Vorteil ist allerdings, dass git-Repositories als Quellen verwendet werden und dass man mehrere Repositories gleichzeitig als Quellen verwenden und in einer einheitlichen Dokumentation kombinieren kann.
Ein wichtiges Konzept sind dabei "virtuelle Datei Objekte": Antora sammelt die Daten aus verschiedenen Quell-Repositories ein und verwendet so etwas wie ein internes zusammengesammeltes Repository, wobei für die Referenzen zwischen Inhalten Page IDs und Cross References verwendet werden. Die Verwendung dieser Referenzen ist zum einen die Grundidee von Antora, und sie stellt gleichzeitig eine Einbahnstraße dar, weil diese Referenzen außerhalb Antoras nicht mehr funktionieren.
Im DataHandwerk-Projekt beschreibe ich, wie man aus der Repository-Datenbank automatisch generierte Datenbank-Dokumentationen erstellen kann, die final von Antora gerendert werden: Database documentation generator.
Ich hatte auch versucht, das Datenbank-Projekt mit seinem Code für alle Objekte direkt in Antora einzubinden. Mit doctoolchain wäre das recht einfach gewesen. Für Antora mussten dazu die Inhalte das Datenbank-Projekts in ein separates Repository kopiert werden, damit die Inhalte in der von Antora benötigten Form vorliegen. Das funktionierte, allerdings habe ich diese Idee verworfen und exportiere alle Inhalte für die Datenbank-Dokumentation direkt aus der Repository-Datenbank.
Auch das Ergebnis der DataHandwerk-Datenbank-Dokumentation kann man sich anschauen. Beispielsweise docs.RepoObject_Adoc
-
eine Seite pro Datenbank-Objekt
-
Dokumentation realer und virtueller Primary Keys
-
Dokumentation von Objekt-Referenzen und auch von Zeilen-Referenzen
-
Visualisierung von Referenzen und realen und virtuellen Foreign Keys als PlantUML-Diagramme
PlantUML
Die Visualisierungen erstelle ich direkt aus dem SQL Server heraus für jedes Objekt als PlantUML Diagramme. Diese Diagramme werden vom Asciidoctor bzw. einer entsprechenden Erweiterung gerendert. Pro Datenbank-Objekt erstelle ich derzeit 5 Diagramme
-
Objekt-Referenzen mit jeweils einem Level der Vorgänger und einem Level der Nachfolger
-
Zeilen-Referenzen mit jeweils einem Level der Vorgänger und einem Level der Nachfolger
-
Objekt-Referenzen mit Vorgängern aller Level
-
Objekt-Referenzen mit Nachfolgern aller Level
-
Beziehungen zwischen realen und virtuellen Fremdschlüsseln (nur für Tabellen und Sichten)
Quelle für die Diagramme ist die DataHandwerk-Repository-Datenbank, welche auch die Definition virtueller Indizes, virtueller PK und die Ermittlung von Spalten-Referenzen unter Verwendung von sqlparse beinhaltet. Hier ein paar Beispiele für die Sicht sqlparse.RepoObject_SqlModules_21_statement_children_helper
Object Reference Diagram
Object Reference Diagram - Referenced
Object Reference Diagram - Referencing
Column Reference Diagram
Über mich
Mein Name ist Germo Görtz. Und ich bin darauf spezialisiert, analytische Informations-Systeme und Berichts-Systeme technisch zu konzipieren und zu implementieren, damit sie fachlich funktionieren.
Meine Kunden erwarten von mir keine strategische Beratung, denn sie sind Profis, kennen ihr Fach und ihre Ziele.
Ich bin der Weihnachtsmann des kompetenten Controllers.
Je kniffliger die Aufgabe, desto größer mein Mehrwert.
Ihr Kittel brennt? Ich bin Ihr Feuerlöscher!
Sie wissen, wo Sie hinwollen. Ich analysiere und verstehe Ihre Ziele, dann werde ich Ihr Pfadfinder und führe oder fahre oder fliege Sie zu Ihren Zielen.
Meine technische und konzeptionelle Erfahrung ergänzt Ihre fachliche Erfahrung
⇒ für Ihre Karriere und Ihren Erfolg!
Folgende Faktoren machen unser gemeinsames Projekt besonders fruchtbar:
-
Exzellenz durch Kompetenz
-
Handwerk statt Fließband
-
Vertrauen in Experten (Technokratie statt Demokratie[1])
Für die Umsetzung nutze ich primär meine in Jahrzehnten erworbenen Kenntnisse und Erfahrungen mit der Microsoft BI Plattform: SQL Server, Power BI, relationale und analytische Datenbanken, maschinelles Lernen. Meine besondere Stärke ist die Erstellung von Datenmodellen.
Vergütung:
-
Besonders motivierend ist eine Zusammenarbeit, bei der ich Expertise und Zeit investieren kann, um am messbaren Erfolg beteiligt zu werden.
-
Gewerke und Festpreise sind möglich.
-
Ansonsten tausche ich Zeit gegen Geld und werde nach Stunden bezahlt.
Am Ende meines IT-Profils finden Sie Referenzen zufriedener Kunden.
Lernen Sie mich kennen, bewerben Sie sich mit Ihren Ideen und Projekten, investieren Sie in die Zusammenarbeit mit mir:
⇒ für Ihren Erfolg!
Schreiben Sie mir, rufen Sie mich an, buchen Sie einen Termin!