Ich bin in meiner Familie der Nerd. Ich kümmere mich um den Internetzugang, das WLAN, die Speicherung der Familienfotos, etc. Ja manchmal kümmere ich mich sogar um Drucker.

Meine Familie vertraut darauf, dass das Heimnetzwerk die meiste Zeit des Jahres reibungslos funktioniert. Und wenn dies nicht der Fall ist, ist es mein Job, die Sache wieder in Ordnung zu bringen.

Erkennt ihr euch in dieser Beschreibung wieder? Dann habe ich gleich noch weitere Fragen an euch.

Stellt euch vor, dass ihr eines Tages nicht mehr für eure Familie da sein könnt und eure Angehörigen plötzlich allein mit der IT-Umgebung zurechtkommen müssen, die ihr hinterlassen habt.

• Wie bereitet ihr eure Familie auf diesen Fall vor?
• Habt ihr mit euren Angehörigen mal über dieses Thema gesprochen?
• Wie dokumentiert ihr euer Heimnetzwerk, sodass eure Angehörigen etwas mit der Dokumentation anfangen können?

Bitte teilt eure Erfahrungen und Ideen in den Kommentaren zu diesem Beitrag. Habt ihr selbst schon zu diesem Thema gebloggt? Dann teilt doch bitte den Link zu eurem Beitrag mit mir und den Leserinnen und Lesern dieses Blogs.

Gedanken zur Dokumentation

• Die Dokumentation soll in ausgedruckter Form vorliegen, um auch bei einem Totalausfall des Heimnetzwerks nutzbar zu sein
• Es ist eine leichtverständliche Sprache zu wählen, die ohne Fachchinesisch auskommt oder notwendige Fachbegriffe erklärt, damit auch Nicht-IT-Personal den Text verstehen und Anweisungen folgen kann
• Hinzugezogenem IT-Support-Personal soll die Dokumentation ebenfalls nützlich sein
• Die Gliederung orientiert sich an Anwendungsfällen der Nutzer; mögliche Überschriften sind
  • Wie kommt das Internet ins Haus?
  • Wie wird das Internet im Haus verteilt?
  • Wo finde ich unsere Fotos, Videos, Dokumente und digitalen Einkäufe?
  • Was kann ich tun, wenn
    • das Internet nicht geht
    • das WLAN nicht geht
    • das weiße Ding im Keller blinkt/piept

Gerade der Abschnitt zur Entstörung von IT-Komponenten wird sicherlich eine Herausforderung. Generationen von Supportern werden ein Lied davon singen können, doch es hilft ja nunmal alles nichts. Wir sind unseren Angehörigen diese Informationen schuldig, wollen wir sie nicht hilflos zurücklassen.

Für mich ist eine Dokumentation, mit der ein Mensch mit IT-Affinität arbeiten kann das Muss und Hinweise zur Entstörung für technische Laien die Kür.

• Was denkt ihr?
• Könnt ihr meinem Ansatz folgen?
• Habe ich etwas vergessen?

Trennung von Heimlabor und Heimnetzwerk

Wie viele Nerds betreibe auch ich ein kleines Heimlabor. Beim Aufbau des Heimnetzwerks habe ich darauf geachtet, dass mein Heimlabor komplett abgeschaltet werden kann, ohne die Funktion des Heimnetzwerks und den Internetzugang negativ zu beeinflussen.

Dies ermöglicht es mir, in meinem Heimlabor häufige Änderungen durchführen zu können, ohne dass dadurch Änderungen an der Notfalldokumentation notwendig werden.

Frisch ans Werk

Dann werde ich mal ein Git-Repository im Heimnetzwerk erstellen und ein LaTeX-Dokument beginnen.

Ich freue mich, an dieser Stelle von euren Ideen und Vorgehensweisen zu lernen und das Thema mit euch zu diskutieren.

In dieser Episode der Linux Jahresschau geht es um das Jahr 1995

Der Beitrag Linux Jahresschau - Das Jahr 1995 erschien zuerst auf MichlFranken.

In dieser Episode der Linux Jahresschau geht es um das Jahr 1994

Der Beitrag Linux Jahresschau - Das Jahr 1994 erschien zuerst auf MichlFranken.

In dieser Episode der Linux Jahresschau geht es um das Jahr 1993

Der Beitrag Linux Jahresschau - Das Jahr 1993 erschien zuerst auf MichlFranken.

In dieser Episode der Linux Jahresschau geht es um das Jahr 1992

Der Beitrag Linux Jahresschau - Das Jahr 1992 erschien zuerst auf MichlFranken.

In dieser Episode der Linux Jahresschau geht es um das Jahr 1991

Der Beitrag Linux Jahresschau - Das Jahr 1991 erschien zuerst auf MichlFranken.

Ein Freund bat mich kürzlich um meine Meinung zum Thema Software-Verteilung und Dokumentation des Installations- bzw. Bereitstellungsprozesses. Die Gedanken, die ich mir dazu gemacht habe, möchte ich an dieser Stelle mit euch teilen. Dabei schreibe ich aus dem Blickwinkel eines Systemintegrators, der von Dritten erstellte Software integrieren und betreiben muss.

Den Anwendungsentwicklern, Software-Architekten und Produkt-Managern unter euch soll dieser Text als Information dienen, was ich und ggf. weitere Personen meiner Zunft von einer Dokumentation erwarten bzw. wie wir uns Software-Verteilungsprozesse vorstellen.

Als Leser seid ihr alle eingeladen, eure Gedanken ebenfalls zu teilen und eine Diskussion zu diesem Thema zu führen.

Das Szenario

Ich habe bei meinen Gedanken ein Szenario im Kopf, in dem ein Anwendungsentwickler eine Anwendung in einer Sprache seiner Wahl schreibt. Diese Anwendung soll später über ein Web-Frontend erreichbar und nutzbar sein. Die Anwendung benötigt eine Datenbank, um Informationen darin abzulegen. Binärdateien werden ggf. außerhalb der Datenbank in einem Dateisystem gespeichert.

Die Anwendungsentwickler freuen sich, wenn ihre Software einen hohen Verbreitungsgrad erreicht. Dazu muss die dazugehörige Dokumentation folgende Informationen bieten.

Werkzeuge zum Erstellen und Ausführen der Anwendung

• Welcher Compiler ab welcher Version wird benötigt?
• Welche Bibliotheken werden ab welcher Version benötigt?
• Sind abweichende Versionen möglich oder funktioniert nur genau eine?
• Welche Laufzeitumgebung wird benötigt?
• Was ist in welcher Reihenfolge zu tun, um vom Quelltext zu einem ausführbaren Programm zu kommen?

Voraussetzungen zur Integration der Anwendung

• Wird eine Datenbank benötigt?
• Welche Datenbank-Management-Systeme werden unterstützt?
• Ab welcher Version?
• Über welche Rechte muss ein DB-User mindestens verfügen, damit der Anwendungs-Installer die notwendigen Tabellen, Views, etc. erstellen kann?
• Welche Webserver werden unterstützt?
• Welche Protokolle, Parameter bzw. Optionen sind für die Kommunikation mit der Anwendung notwendig?

Ich bin immer enttäuscht, wenn hier auf ein einziges System eingeschränkt wird. Dies limitiert unnötig den Nutzerkreis.

• Wird ein Snakeoil-Zertifikat mitgeliefert oder hat der Systemintegrator dieses beizustellen? Eigene Zertifikate auf Wunsch verwenden zu können ist obligatorisch.

Die bis jetzt genannten Informationen müssen so umfassend sein, dass Paketbetreuer bzw. Software-Paketierer daraus Debian-, Flatpak-, RPM-, Snap-Pakete, Container-Images und Windows-Installer bauen können.

Nehmen die Anwendungsentwickler in Personalunion die Rolle von Software-Paketierern wahr, scheint es dennoch unrealistisch, dass sie allein alle Formate unterstützen können. Sie sollten sich für einige wenige Formate entscheiden, die auf möglichst vielen Plattformen lauffähig sind. In dem von mir gedachten Szenario sind dies OCI-kompatible Container-Images.

Bei einer GUI-Anwendung würde ich mich vermutlich für Flatpak entscheiden. Die Paketierung als DEB oder RPM würde ich auf jeden Fall den Paketbetreuern der jeweiligen Distributionen überlassen.

Systemintegration

Für den Systemintegrator, welcher den Webserver, die Anwendung und die Datenbank zusammenbringt (integriert), muss klar beschrieben werden:

• Gibt es ein fertiges Container-Image? Wo bekommt man es her?
• Optional: Wie erstellt man das Container-Image selbst?
• Welche (Umgebungs-)Variablen gehören zum Image? Welche Werte können diese annehmen?
• Ein Kommunikationsdiagramm, damit der Sysadmin weiß, was wann mit wem spricht und welche Firewall-Regeln evtl. benötigt werden.

Referenzimplementierungen sind ebenfalls schön. Diese sollten für Docker, Docker-Compose, Kube-YAML (K8s) und Podman bereitstehen. Die Doku zum Container-Image muss jedoch so ausgestaltet sein, dass auch ohne Referenzimplementierung die Instanziierung mit den verschiedenen Engines und Orchestrierern gelingen kann.

Was Sysadmins (wie ich) nicht mögen

Ich mag es nicht, wenn in den Abhängigkeiten ein Webserver (Apache, NGINX, lighttpd) oder ein Datenbank-Management-System unnötig hart verdrahtet ist. Gleiches gilt für die Festlegung der zu verwendenden Container-Registries. Ich will dem Installer sagen können, wo er die Images findet und nicht auf den Dockerhub festgelegt werden.

Und ja, mir ist bewusst, dass eine gute Dokumentation genauso viel Aufwand und Pflege bedeutet wie der Quelltext einer Anwendung selbst. Aber ist es eine Alternative, wenn Systemintegratoren die Anwendung nach dem ersten Installationsversuch hassen?

Eure Meinung ist willkommen

Wie steht ihr als Entwickler zum Thema Dokumentation? Was erwartet ihr als Sysadmin und User von ihr?

Stimmt ihr mit mir überein oder habt ihr ganz andere Ansichten dazu? Nutzt gern die Kommentarfunktion und lasst es mich wissen.