Bei der Nordlicht Reisen GmbH wohnt Wissen in Köpfen. Wer krank ist, nimmt das Wissen über die Auslieferung des Buchungsportals mit. Die neue Kollegin fragt, wie eine Version entsteht, und bekommt drei verschiedene Antworten. Außerdem will der Vertrieb wissen, was die neue Version bringt, und die Partner brauchen eine Beschreibung der Schnittstelle. Ihre Aufgabe: dafür sorgen, dass Dokumentation dort liegt, wo der Code liegt, sich aus dem Arbeitsfluss ergibt und nicht von Hand nachgezogen werden muss.

Das sind die Fähigkeiten der Prüfung: Wikis und Prozessdiagramme (Markdown, Mermaid), Dokumentation für Releases und APIs und Dokumentation aus dem Git-Verlauf.

Vorwissen: Pull Requests, Issues und Rückverfolgbarkeit stehen in Lektion 1.1, Boards und GitHub in Lektion 1.2. Zu Markdown und Git setzt der Kurs Grundkenntnisse voraus. Versionen und Feeds lehrt K3, Lektion 3.7.4; Versionierung als Strategie Lektion 3.2.

Hinweis: Alle Angaben stammen aus der Dokumentation von Microsoft Learn, GitHub und Git; die Seiten stehen unter „Weiterlesen“. Die Befehle, Dateien und Menüpfade dieser Lektion wurden nicht ausgeführt; sie stammen aus der Referenz von Microsoft und GitHub.

Wikis

Azure DevOps: ein Wiki je Projekt, von Git getragen

Nach Microsofts Seite „Create a wiki for your project“ hat in Azure DevOps jedes Projekt ein Wiki, und ein Git-Repository trägt es. Beim Anlegen eines Projekts entsteht das Repository noch nicht; Sie legen es an, oder Sie veröffentlichen vorhandene Markdown-Dateien aus einem Repository. Jeder mit Zugang zum Projekt kann das Wiki ansehen, auch Stakeholder. Zum Bearbeiten müssen Sie Mitglied der Gruppe Contributors sein, mit mindestens Basic-Zugriff.

Es gibt zwei Arten, laut Seite „Provisioned wiki vs. published as code wiki“:

Projekt-Wiki (provisioned wiki) Als Code veröffentlicht (code wiki)
Ort der Seiten im Bereich Wiki, Pages als Dateien im Repository, unter Repos oder Code
Pflege Seiten direkt im Wiki bearbeiten Markdown wie Code ändern, Pull Request, Review
Anzahl eines je Projekt mehrere versionierte Wikis je Projekt möglich
Voraussetzung Wiki-Repository anlegen Azure Repos mit einem Git-Repository im Projekt

Die Ordnerstruktur ist bei beiden gleich: Das Repository eines Projekt-Wikis heißt <Projektname>.wiki, sein Hauptbranch wikiMain. Es enthält eine Datei je Markdown-Seite auf oberster Ebene, eine Datei .order in jedem Ordner (sie legt die Reihenfolge fest; was dort fehlt, steht am Ende der Liste), einen Ordner je Seite mit Unterseiten und den Ordner .attachments für Anhänge. Eine Seite mit Unterseiten braucht eine Markdown-Datei und einen gleichnamigen Ordner im selben Ordner. Auf dem Branch wikiMain können Sie wie bei anderen Branches Richtlinien einrichten.

Als Code veröffentlichen lässt sich im Browser (Wiki, Publish code as wiki: Repository, Branch und Ordner wählen, Namen vergeben, Publish) oder mit der Azure CLI:

PowerShell
az devops wiki create --name "Portal-Doku" --type codewiki --repository nordlicht-portal --mapped-path /docs --version main

Die Referenz nennt für az devops wiki create unter anderem --name, --type (projectwiki oder codewiki), --repository, --mapped-path (die Seite führt ihn als „mapped path“ des Wikis auf; / veröffentlicht ab der Wurzel), --version (der Branch) sowie --org und --project. Der Kopf des Branches ist dem veröffentlichten Wiki zugeordnet; Änderungen am Branch erscheinen im Wiki ohne weiteren Ablauf. Laut Microsoft lassen sich bis zu 10 Branches je veröffentlichtem Code-Wiki veröffentlichen. Der Vorteil: Dokumentation folgt dem Pull-Request-Ablauf des Codes, bekommt aber Inhaltsverzeichnis, Hierarchie, Versionen und eine Suche.

Weitere Hinweise: Ein Inhaltsverzeichnis setzt [[_TOC_]] (laut Microsofts Hinweisen zu Azure DevOps Server 2019); Anhänge ziehen Sie in den Editor, sie landen in .attachments; Anker springen zu Überschriften (kleingeschriebene Überschrift mit Bindestrichen). Für Arbeitselemente genügt # mit Nummer, für Personen @.

GitHub: ein Wiki je Repository

Nach GitHubs Seite „About wikis“ hat jedes Repository einen Bereich Wiki für langen Inhalt zum Projekt. Standardmäßig dürfen nur Personen mit Schreibzugriff das Wiki ändern; bei öffentlichen Repositories können Sie jedem auf GitHub.com das Beitragen erlauben. Wikis privater Repositories sehen nur Personen mit Zugriff auf das Repository. Es gibt ein weiches Limit von 5.000 Dateien. Sie schreiben in Markdown (oder einem anderen unterstützten Format), und GitHub rendert Formeln, Diagramme, Karten und 3D-Modelle. Ob das Wiki selbst ein Git-Repository ist, nennt diese Seite nicht.

Wohin mit welcher Dokumentation?

Wenn … dann … weil …
die Dokumentation mit dem Code zusammen geprüft werden soll Markdown im Repository (README, docs/) sie läuft durch denselben Pull Request
Azure DevOps genutzt wird und die Doku ein Inhaltsverzeichnis und Suche braucht als Code veröffentlichtes Wiki Dateien bleiben im Repository, das Wiki bekommt Struktur
ein Team schnell Wissen sammeln will, ohne Review Projekt-Wiki Seiten lassen sich direkt bearbeiten
das Team bei GitHub arbeitet README und docs/, bei Bedarf das Wiki des Repositorys GitHub hat kein Wiki je Projekt
Dokumentation Zugriff für Nichtentwickler braucht Wiki oder README mit Rechten für Lesende Wiki-Lesen ist in Azure DevOps auch für Stakeholder möglich