Open-Source-Guidelines_2024.pdf

[Seite 1]

Open Source

Guideline Dokumentation

Einleitung

Open-Source-Software (OSS)-Projekte werden auf Quellcode-Plattformen (OpenCoDe, Gitlab, GitHub, ...) häufig in Form (mehrerer) Repositories zugängig gemacht. Repositories fungieren für den Betrachter als zeitlich versionierter Ordner.

Notwendige Dokumentationen oder Einstiegspunkte in weitere Dokumentationen werden hierbei häufig als Textdateien abgelegt, die oft mit der Dateiendung .md kodiert sind. .md steht hierbei für Markdown. Das Markdown-Format bietet Entwicklern eine rudimentäre Formatierungsmöglichkeit zur Strukturierung von Texten, etwa mit Überschriften, Links oder Bildern und erleichtert dem Leser die Erfassung des Inhalts.

Einige dieser Textdateien nehmen in Repositories besondere Rollen ein, etwa in Form des README.md, welches als Einstiegspunkt in Repositories genutzt wird, um Name, Lizenz und weitere Eigenschaften des Projekts vorstellen zu können. Im Folgenden werden einige dieser Dokumentationsaspekte aufgegriffen und Vorschläge für das Ablegen der Dokumentation in Repositories gemacht.

Es ist zu empfehlen, insbesondere weiterführende und umfangreiche (technische) Dokumentationen in externe Webseiten auszulagern, um etwa eine Durchsuchbarkeit zu ermöglichen. Diese Webseiten werden dann in der im Repository abgelegten Dokumentation verlinkt. Die jeweilige (Text-)Datei im Repository dient in diesem Falle lediglich als Einstiegspunkt. Zur Erstellung solcher Dokumentations-Webseiten sind im Folgenden verschiedene Softwarelösungen exemplarisch aufgeführt.

Folgende Dokumentationsblöcke sollten in OSS-Projekten beinhaltet sein:

Installations- und Betriebsdokumentation

Ziel: Dritte befähigen, die Systeme auf eigener Infrastruktur bereitzustellen und in einem produktiven Umfeld betreiben zu können.

➢ Definition der Systemgrenzen • „Was brauche ich an Drittservices?“ ✓ Beispiel: Datenbanken, Broker, Hardware, Betriebssystem etc.

➢ Definition von Anforderungen an die Betriebsumgebung • realistische Angaben (z.B. Speicherplatz möglichst präzise gestalten)

Open Source Guidelines zur Dokumentation | Koordinierungs- und Transferstelle Modellprojekte Smart Cities (MPSC)

[Seite 2]

➢ Hinweise für Produktivbetrieb • technische Härtungsmaßnahmen ✓ damit der Betrieb auch „sicher“ umgesetzt werden kann und der Betreiber eine Chance hat, Risiken einzuschätzen ✓ Welche Maßnahmen sind bereits umgesetzt? welche müssen vom Betreiber durchgeführt werden? ✓ weiterhin: Benennung der Komponenten, um das System absichern zu können

• Skalierungsmöglichkeiten ✓ Wie kann mit steigender Last auf dem System umgegangen werden?

Aktualisierungs- und Entwicklerdokumentation

Ziel: Dritten ermöglichen, die Anwendung zu aktualisieren und zu erweitern und dadurch in einem gewarteten Zustand zu halten.

➢ (Software-)Architektur vermitteln • Welche Module gibt es? • Was sind deren Aufgaben? • Welche Abhängigkeiten zu anderen Technologien gibt es?

➢ Vermeidung komplexer, nicht-standardisierter Lösungen • schlanke Lösungen sind zu empfehlen, da sie weniger Wartungsaufwand bedeuten • standardisierte Lösungen brauchen weniger Dokumentation, da auf Bestehendes verwiesen werden kann • komplexe Architekturen erfordern viel Dokumentation, damit es nicht zu Missverständnissen kommt

Nutzerdokumentation

Ziel: Dritten ermöglichen, (Prozess)-Konzepte zu verstehen und gegenüber eigenen Nutzern Anfragen beantworten zu können

➢ Kernkonzepte kurz erklären • Was ist der Nutzen der Software? • Welche fachlichen Funktionen gibt es?

➢ Dokumentation nach Anwendungsfällen strukturieren • Nutzer suchen in der Dokumentation, wenn sie an einem bestimmten Anwendungsfall hängen bleiben • ein allgemeiner Überblick hilft das System zu verstehen, die Anwendungsfall spezifische Dokumentation hilft bei der Benutzung

➢ Verlinkungen intensiv nutzen • zentrale Konzepte einmal erklären, dann an allen relevanten Stellen darauf verlinken

Open Source Guidelines zur Dokumentation | Koordinierungs- und Transferstelle Modellprojekte Smart Cities (MPSC)

[Seite 3]

Weitere Dokumentation

Ziel: Klare Regeln für die Zusammenarbeit aufstellen

➢ Lizenzierung • Datei: LICENSE.md • Welche Lizenzen liegen vor?

➢ Mitarbeit • Code of Conduct/Verhaltenscodex ✓ Datei: CODE_OF_CONDUCT.md / CONTRIBUTING.md ✓ Standards definieren ✓ Qualität von Beiträgen ✓ Umgangston ✓ weitere Regelungen: Abtritt von Rechten am Code, LLM Code verbieten, ...

• Issue-Templates ✓ technische Maßnahme, um neuen Tickets Struktur geben zu können ✓ exemplarischer Inhalt:  zuerst offene Tickets durchsuchen, bevor neue Tickets eröffnet werden  zwingend notwendiger Inhalt bei Fehlerberichten  ...

• festlegen, wo Diskussionen stattfinden sollen ✓ Achtung bei GitHub: Wenn externe Diskussionsplattformen genutzt werden (z.B. Foren), sollte die Diskussionsfunktion im Repository deaktiviert werden!

➢ Ansprechpartner festhalten ➢ Meldekette „Sicherheit“ definieren • Datei: SECURITY.md • Über welchen Kanal kann eine Responsible Disclosure (=vertrauliche Meldung von Sicherheits- problemen) durchgeführt werden?

Form der Dokumentation

➢ Readme lediglich als Einstiegspunkt / Hub nutzen ➢ Bereitstellung einer einheitlichen, versionierten und durchsuchbaren Dokumentation ➢ PDF- / Office-Dateien meiden und stattdessen Generatoren nutzen, um umfangreichere Dokumentation als Webseite zu erzeugen

Beispiele für Generatoren (Text)

Diese Generatoren sind meist zur Erstellung von umfangreicher, textueller Dokumentation gedacht. Die Ausgangsbasis der Dokumentation kann dann versioniert werden und die eigentliche Dokumentation immer wieder aktuell generiert und auf einem Webserver abgelegt werden.

Open Source Guidelines zur Dokumentation | Koordinierungs- und Transferstelle Modellprojekte Smart Cities (MPSC)

[Seite 4]

➢ Docusaurus ➢ Gitbook ➢ Readthedocs ➢ ...

Beispiele für Generatoren (Code)

Diese Generatoren und Technologien sind meist eng mit dem Code verbunden und erzeugen eine maschinen- lesbare Entwicklerdokumentation. Damit kann beispielsweise direkt Code zur Anbindung von externen Systemen generiert werden, da die Schnittstellen eindeutig beschrieben sind.

➢ OpenAPI ➢ JavaDoc ➢ Sandcastle ➢ ...

Open Source Guidelines zur Dokumentation | Koordinierungs- und Transferstelle Modellprojekte Smart Cities (MPSC)