Wissensdokumentation

Diese Seite behandelt Grundlegende Themen die Einsteigern zu Internetfähigen Geräten und PCs dazu dienen soll sich mit dem Linux basierten System zurechtzufinden und selbständig Probleme zu lösen.

Effiziente Wissensdokumentation in der IT

Version: 1.2 Von: --Ulf 22:30, 22. Apr. 2024 (CEST) (basieren auf v1.1 von plocki <refWissensdokumentation v1.1 von plocki, datum=2024-04-19, abruf=2024-04-22</ref>

Einleitung

Gelerntes oder auch seltene Abläufe richtig zu dokumentieren, ist gar nicht so einfach. Zum einen muss man seine Notizen später wiederfinden. Zum anderen muss man sie auch verstehen, auch wenn die Umgebung sich weiterentwickelt hat.

Hilfreich zum Verständnis dieses Artikels

Eine mögliche, allgemeine Struktur eines Artikels:

• Titel/Überschrift
• Datum!
• Voraussetzungen, falls erforderlich (Link zu den erforderlichen Informationen später einfügen)
• Einleitung / Überblick
• Hauptteil
• Schluß / Referenzen, hilfreiche Quellen (Links mit Datum des letzten Aufruf)

Einleitung / Motivation

Zunächst sollte man sich folgednde Fragen

• Was wird erklärt? Was ist das Ziel?
• Welche Methodik wurde wie angewendet?

Dieses Dokument beschreibt allgemeine Grundlagen, wie eigenes Wissen, Problemlösungen, seltene Abläufe sinnvoll dokumentiert werden können. Beispielhaft wird auf die Dokumentation in unserem LUG-VS Wiki eingegangen, ohne in die Details der Wikisystax einzugehen.

Hauptteil

• Sinnvolle Struktur wählen
• Vom Allgemeinen zum Speziellen (ggf. mit konkreten Beispielen abschließen)
• Hauptsätze sind gut!
• Beim Thema bleiben: "Doku erstellen". NICHT Wiki Syntax
• Bilder, Tabellen, Sichworte, Fußnoten…​ sinnvoll einsetzten
• technischen/komplizierte Themen exakt formulieren
• Codebeispiele minimal beschrieben
• Abkürzungen erläutern (ggf. Abkürzungsverzeichnis erstellen)
• …​

Allgemein: Speicherorte und Formate

Bei der Wahl des Speicherorts bzw. des Speicherformates, sollte man folgende Anforderungen beachten:

   Wie finde ich die Information einfach wieder (Stichpunktsuche, chronologische Suche, …​) (siehe auch Informationsbeschaffung)

   Wo kann ich die Dokumente gut wiederfinden, selbst wenn mein PC / Notebook gerade nicht mehr funktioniert oder ich keinen Zugriff mehr habe?

   Falls es sich nicht aus der Auswahl des Ortes ergibt, in welchen Format speichere ich die Daten (dass sie eben auch einfach durchsuchbar sind)?

   Sollen die Informationen für Andere zur Verfügung stehen (bedingt, dass keine sensiblen Daten in der Dokumentation vorhanden sind)?

Beispiel: Ablage im Internet in unserem LUG-VS-Wiki [1]

Für die Ablage der Dokumente im Internet und insbesondere in unserem LUG-VS-Wiki, spricht:

   Für jeden, jederzeit gut erreichbar, sofern eine Internetverbindung (notfalls mit einem Zweitgerät) besteht

   Keine besondere Hardware oder Software erforderlich

   Zugang für LUG-VS bekannte Personen einfach verfügbar (muss nur bei Ulf angefordert werden)

   Struktur vorgegeben

   Integration von Bildern und Dokumenten möglich

   Dokumente werden automatisch versionsverwaltet (also man kann sich ältere Stände wieder anschauen, obwohl man selber oder jemand anderes Informationen verändert oder entfernt hat)

   Andere mit Zugang können die Dokumentation erweitern oder ergänzen

   Daten werden in der Regel von uns (Serveradmins) regelmäßig gesichert

Dagegen spricht:

   Oben genannte Vorteile sind teilweise auch Nachteile (insbesondere der allgemeine Zugriff)

   Man muss sich in die Formatierung des Wikis erst einarbeiten

Beispiele für Alternativen

   Markdown, Asciidoc, usw

   Webseiten-Blog

   (Online)Office

   Git-Wiki

   …​

Schluß / Fazit / Quellen

• Qualität der Links prüfen
• Links mit Datum des letzten Aufrufs versehen
• ggf. weiterführende Themen verlinken
• …​

Beispiel aus dem Ubuntu-Wiki: https://wiki.ubuntuusers.de/ls/

Speicherorte

Bei der Wahl des Speicherorts bzw. des Speicherformates, sollte man folgende Anforderungen beachten:

1. Wie finde ich die Information einfach wieder (Stichpunktsuche, chronologische Suche, ...) (siehe auch Informationsbeschaffung)
2. Wo kann ich die Dokumente gut wiederfinden, selbst wenn mein PC / Notebook gerade nicht mehr funktioniert oder ich keinen Zugriff mehr habe?
3. Wie strukturiere ich meine Dokumentation richtig?
4. Falls es sich nicht aus der Auswahl des Ortes ergibt, in welchen Format speichere ich die Daten (dass sie eben auch einfach durchsuchbar sind)?
5. Sollen die Informationen für andere zur Verfügung stehen (bedingt, dass keine sensiblen Daten in der Dokumentation vorhanden sind)?

Ablage im Internet z.B. in unserem LUG-VS-Wiki

Für die Ablage der Dokumente im Internet und insbesondere in unserem LUG-VS-Wiki, spricht:

1. Für jeden, jederzeit gut erreichbar, sofern eine Internetverbindung (notfalls mit einem Zweitgerät) besteht
2. Keine besondere Hardware oder Software erforderlich
3. Zugang für LUG-VS bekannte Personen einfach verfügbar (muss nur bei Ulf angefordert werden)
4. Struktur vorgegeben
5. Integration von Bildern und Dokumenten möglich
6. Dokumente werden automatisch versionsverwaltet (also man kann sich ältere Stände wieder anschauen, obwohl man selber oder jemand anderes Informationen verändert oder entfernt hat)
7. Andere mit Zugang können die Dokumentation erweitern oder ergänzen
8. Daten werden in der Regel von uns (Serveradmins) regelmäßig gesichert

Dagegen spricht:

1. Oben genannte Vorteile sind teilweise auch Nachteile (insbesondere der allgemeine Zugriff)
2. Man muss sich in die Formatierung des Wikis erst einarbeiten

Dokumentationsstil und -inhalt

Hier ist insbesondere bei IT-nahen Themen darauf zu achten, dass die Information auch in ein paar Jahren mit einer dann neuen Software-Version gültig sein sollte. Dabei hat es sich gezeigt, das Informationen die sich auf Befehle im Terminal (CLI = Command Line Interface = Kommandozeile) sich über lange Zeiträume nicht oder wenig ändern. Das grafische Interface von Programmen wechselt sich unter Umständen aber wesentlich (Verschiebung von Menüpunkten oder Umstrukturierung generell.

Struktur

Wichtig ist, eine einheitliche Struktur beizubehalten. So sollte der Aufbau von IT Dokumentationen folgende Punkte berücksichtigen:

1. Kurzer Überblick oder Einleitung, worum es geht. Hier sollten ein paar wichtige Stichpunkte enthalten sein, nach denen man später unter Umständen sucht
2. Es sollten die Voraussetzungen bzw., falls erforderlich die Installation der benötigten Bestandteile beschrieben werden
3. Nun kann man den eigentlichen Sachverhalt beschreiben, wobei man darauf achten sollte, dass man nicht zu viel Text schreibt, lieber ein paar typische Fälle beschreibt und z.B. vorgeschlagenen Parameter oder Einstellungen kurz, am besten in einer Tabelle oder Bild, beschreiben
4. Wenn nicht schon am Anfang geschehen, am Ende noch ein paar Referenzen zu hilfreiche Quellen einbauen (wobei darauf zu achten ist, möglichst so genannte Permalinks zu verwenden)

Quellenangaben:

1. Videoaufzeichnung des Vortrags auf der LUG-VS PeerTube Instanz

---

Zurück zur Themenübersicht oder Zurück zur Hauptseite