Einführung

Es gibt verschiedene Wege, auf Informationen zuzugreifen:

  1. (chrono)logisch, wie Seite für Seite, Zeile für Zeile zu lesen, bis Sie das Ende der Publikation erreichen,
  2. thematisch, wie zum Inhaltsverzeichnis zu gelangen und direkt zu dem Teil zu springen, der Sie interessiert, vorausgesetzt, der Inhalt ist in sinnvolle Inhaltseinheiten unterteilt,
  3. transversal, wie einem Abschnitt „verwandte Beiträge" zu folgen, der auf Inhaltsähnlichkeit basiert (manuell definiert, mit Tags & Schlüsselwörtern, oder durch KI-Themenanalyse gelernt), oder expliziten Querverweisen. Zum Beispiel haben die meisten Websites Archive, die alle Seiten mit einem bestimmten Tag/Schlüsselwort auflisten, Bücher haben Glossare.
  4. hinweisbasiert, wie eine Bibliografie tiefergehender Publikationen oder einen Abschnitt „mehr Infos" am Ende des Inhalts zu präsentieren, oder späteren Inhalt vorwegzunehmen,
  5. quellenbasiert, indem man Verweisen (typischerweise Fußnoten oder Randnotizen) zu Publikationen folgt, aus denen die Information stammt, meist zu Verifikationszwecken,
  6. Informationsbeschaffung, auch bekannt als Suchmaschine.

Sie müssen sie alle zugleich unterstützen, denn sie sind komplementär, und welcher im jeweiligen Kontext der beste ist, hängt vom Vorwissen und den Bedürfnissen des Lesers ab. Keiner dieser Wege ist den anderen überlegen. Das bedeutet, dass in Ihrem Text ein gutes Maß an „Keyword-Stuffing" zu leisten ist, um sicherzustellen, dass die schlüsselwortbasierte Inhaltsanalyse und die Informationsbeschaffung nach Schlüsselwörtern wie erwartet funktionieren.

Ein Handbuch/eine Dokumentation ist kein Kurs, aber sich an eine trockene Liste von Funktionen/GUI-Bedienelementen und deren Definition zu halten, ist… zu trocken. Sie müssen Verbindungen zwischen Inhalten schaffen (was nicht bloß HTML-Links sind). In Ansel beginnen Workflows mit einem Ziel und rollen das Werkzeug auf, um es zu erreichen. Die Dokumentation beginnt mit dem Werkzeug und stellt dar, wie und wo es verwendet werden kann. Aber das sind die beiden Enden des Spektrums, und die Realität liegt immer ein wenig dazwischen.

Wissen ist ohnehin ein Netzwerkgraph . Sie müssen nur auf die Verbindungen zwischen den Knoten achten. Sie sind mindestens ebenso wichtig wie der Inhalt.

Praktische Umsetzung in Ansel

Ansel verwendet Hugo  als sein CMS, sowohl für die Dokumentation als auch für den Rest der Website. Die praktische Umsetzung der oben genannten Prinzipien wird sich mit den Kernfunktionen von Hugo auseinandersetzen müssen.

(Chrono)logischer und thematischer Zugriff

Hugo-Inhalte sind in Sektionen  organisiert, die im Wesentlichen Unterordner des Hauptordners /content sind. Unterordner können unendlich verschachtelt werden. Das Theme der Website stellt die Baumansicht aller Sektionen in der linken Seitenleiste dar, auf breiten Bildschirmen (Desktop). Sektionen und die obersten Ebenen der Untersektionen können auf Wunsch des Nutzers ein- und ausgeklappt werden. Diese Baumansicht liefert das oberste Inhaltsverzeichnis, das als thematischer Zugriff fungiert.

Innerhalb von Sektionen kann die relative Reihenfolge der Seiten manuell mit dem weight-Parameter  in den Markdown-Headern definiert werden, wie folgt:

1---
2title: Documenting Ansel
3date: 2025-10-13
4weight: 9
5---
6
7My content here

Der weight-Parameter ist optional. Wird er nicht verwendet, nutzen die Seitenauflistungen typischerweise das date, um den Inhalt zu ordnen, könnten aber auch eine alphabetische Ordnung nach dem Seitentitel verwenden. Diese Ordnung liefert den (chrono)logischen Zugriff.

Innerhalb von Seiten wird, wenn es mehr als zwei Abschnitte im Inhalt gibt (definiert durch Titel zweiter Ebene, z. B. <h2> in HTML oder ## in Markdown), von Hugo automatisch ein internes Inhaltsverzeichnis in die rechte Seitenleiste eingefügt, auf breiten Bildschirmen (Desktop).

Transversaler Zugriff

Tags können auf der Website mit dem tags-Parameter im Markdown-Header definiert werden, wie folgt:

1---
2title: This page title
3date: 2022-12-04
4tags:
5    - color science
6    - pipeline
7---
8
9Your content

Tags sind optional und werden an mehreren Stellen im Website-Theme als anklickbare Links angezeigt. Ein Klick auf ein Tag öffnet dessen Archiv, das alle Seiten mit diesem Tag auflistet. Das liefert den transversalen Zugriff.

Autoren werden außerdem ermutigt, Querverweise in ihren Inhalt einzufügen, von Website-Seiten zu anderen Website-Seiten, um den transversalen Zugriff zu fördern. Konzepte, die einen Eintrag auf der Website haben, sollten in Links zu der Seite umgewandelt werden, die das jeweilige Konzept beschreibt.

Hinweisbasiert

Autoren steht es frei, am Ende ihrer Seiten einen Abschnitt Bibliografie oder Mehr Informationen mit einer Liste von Publikationen und Links hinzuzufügen. Diese Publikationen können intern oder extern zum Ansel-Projekt sein. Sie können am Rande des im Inhalt behandelten Themas liegen.

Es ist auch möglich, Seiten mit einem Ausblick auf den nächsten logischen Schritt zu beenden, wenn man über Workflows oder Module schreibt.

Quellenbasiert

Hugo unterstützt erweitertes Markdown, das Fußnoten unterstützt . Diese werden empfohlen, um Quellen zu referenzieren, wie folgt:

1The typical observer has Just Noticeable Difference (Delta E) of 2.3[^1]
2
3[^1]: Some Author, Some Publisher, _A real-world, large-sampled, study of vision parameters for white, rich, educated, American students of the Rochester Institute of Technology_, (some year). [URL](https://doi.org/xxxxx)

Ansel hat sich zu diesem Zeitpunkt auf keine bestimmte akademische Formatierung von Quellenangaben festgelegt, obwohl der IEEE-Zitierstil  für den Fußnotenansatz mit numerischem Index am besten geeignet zu sein scheint.

Stellen Sie sicher, dass Sie den DOI  der Publikation angeben, oder zumindest eine langfristige URL, unter der sie jetzt und in Zukunft abgerufen werden kann.

Informationsbeschaffung

Vorerst übernimmt Chantal  diesen Teil. Der Webindex wird manuell und periodisch aktualisiert.

Richtlinien

Schreiben, selbst technisches, ist eine Kunst, die sich nur schwer auf einen Satz fester Richtlinien oder bewährter Praktiken reduzieren lässt, da dies vom Kontext abhängt. Sie sollten darauf achten, nicht päpstlicher als der Papst zu werden. Eine gute Faustregel ist, zu schreiben, um Probleme zu lösen, was bedeutet, sich zunächst zu fragen, warum und von wo der Leser auf der Seite gelandet ist, die Sie schreiben:

  1. Welche Art von Wissen wird beim Leser vorausgesetzt/angenommen?
    • der Leser sollte sich dieser Voraussetzungen idealerweise bewusst sein, also beginnen Sie vielleicht mit einer Liste von Links,
    • alles, was nicht in dieser Liste steht, sollte auf Ihrer Seite definiert und erklärt werden,
  2. Welche Art von Aufgabe versucht der Leser zu erledigen, die ihn auf diese Seite geführt hat?
    • möchte er einen schnellen Spickzettel, oder eine detaillierte Anleitung, oder einen theoretischen Hintergrund? Möglicherweise müssen Sie sich willkürlich für eines entscheiden.
    • das wird entscheiden, welche Hinweise Sie im Text hinzufügen können, um das Wissensnetzwerk zu verbessern,
    • das sollte wahrscheinlich den gesamten Blickwinkel Ihres Inhalts und dessen Länge/Tiefe beeinflussen.

Eine gute Möglichkeit, die Qualität der Dokumentation zu beurteilen, besteht darin, sich die häufig gestellten Fragen (oder am wenigsten verstandenen Themen) in Foren anzusehen. Wenn das Thema bereits abgedeckt ist, aber immer wieder Fragen auftauchen, kann das daran liegen, dass die Dokumentation nicht klar ist oder die relevanten Seiten im Netzwerk vergraben und nicht auffindbar genug sind.

Translated from English by : ChatGPT, Claude. In case of conflict, inconsistency or error, the English version shall prevail.