Was clean code und effiziente Wissens-Strukturierung gemeinsam haben

Wenn ich ein komplexes Thema inhaltlich beschreibe, stellt es mich vor vielfältige Herausforderungen.

Eine übliche Art der Bearbeitung ist die Aufteilung des Inhalts in sog. Topics, die spezielle Aspekte dieses Inhalts beschreiben.
Diese Topics können mit Assoziationen, also Beziehungen untereinander, versehen werden.

Eine Topic Map dient dazu, den Überblick über alle Topics zu erhalten. Sie ist die “Landkarte”, auf der alle Topics und deren Beziehungen verzeichnet sind.
In ihr kann navigiert werden und auch auf die einzelnen Topics über einen Index zugegriffen.

Hierbei stellt sich die Frage, wie umfangreich die einzelnen Topics erstellt werden und welche Aspekte in welchem Topic dokumentiert werden.

Dabei helfen mir die Regeln der Clean Code Developer [1].
Was für Entwickelnde gut ist, kann für Dokumentierende nicht falsch sein.
Im Orangenen Grad sollen folgende Prinzipien eingehalten werden, die ich gleich auf Topics abbilde:

  • Single Level of Abstraction: Die Einhaltung eines Abstraktionsniveaus fördert die Lesbarkeit.
  • Single Responsibility Principle: Fokus erleichtert das Verständnis. Ein Topic mit genau einer Aufgabe ist verständlicher als ein Gemischtwarenladen.
  • Separation of Concerns: Wenn ein Topic keine klare Aufgabe hat, ist es schwer ihn zu verstehen und ggf. zu korrigieren oder zu erweitern.
  • (Source Code) Konventionen: Topics werden häufiger gelesen und recherchiert als geschrieben. Daher sind (Dokumentations-)Konventionen wichtig, die ein schnelles Lesen und Erfassen des Topics unterstützen.

Die Herausforderungen guter Software-Entwicklung und guter technischer Dokumentation ähneln sich also verblüffend.

[1] https://clean-code-developer.de/die-grade/orangener-grad/

Der Inhalt dieser Webseite ist mein persönliches Informationsangebot. Ich übernehme keinerlei Verantwortung für hier verlinkte Inhalte anderer WWW-Seiten und sonstiger Materialien

Tagged with: , , ,
Posted in Wissensmanagement

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: