Zum Hauptinhalt springen

Struktur und Erweiterung

Die Dokumentation ist so angelegt, dass sie langfristig die zentrale Wissensquelle für das Projekt werden kann.

  • Getting Started: Alles, was nötig ist, um lokal loszulegen.
  • Architecture: Wie das System technisch aufgebaut ist.
  • Operations: Wie das System deployed, betrieben und beobachtet wird.
  • Product Logic: Fachliche Regeln und Produktentscheidungen.
  • Security: Zugriff, Secrets, Webhooks und sicherheitsrelevante Betriebsregeln.
  • API: spätere Schnittstellenreferenz.
  • Internal Runbooks: interne, operative Detailanleitungen.

Versionierung​

Docusaurus unterstützt Docs-Versionierung. Wenn eine stabile Produktversion dokumentiert werden soll:

npm run docusaurus docs:version 1.0.0

Vorher sollte entschieden werden, welche Inhalte versioniert werden und welche als laufende Betriebsdokumentation immer aktuell bleiben sollen.

Mehrsprachigkeit​

Die Konfiguration ist mit de als Standardsprache und en als vorbereiteter zusätzlicher Locale angelegt.

Für englische Übersetzungen später:

npm run write-translations -- --locale en

Danach können übersetzte Dokumente unter i18n/en/ ergänzt werden.

Suche​

Die Doku nutzt eine lokale statische Suche über @easyops-cn/docusaurus-search-local. Dadurch ist die Suche unabhängig von externem Algolia-Setup.

API-Doku​

Der Bereich docs/api/ ist als Platzhalter vorbereitet. Später kann dort eine OpenAPI-Spezifikation oder eine generierte API-Referenz eingebunden werden.

Pflege-Regeln​

  • Neue Inhalte in die passende Kategorie einsortieren.
  • Lange Sammelseiten vermeiden.
  • Entscheidungen mit Kontext und Konsequenz dokumentieren.
  • Runbooks klar von Architektur- und Produktlogik trennen.
  • Beispiele mit Platzhaltern statt echten Secrets verwenden.
  • Deutsche Umlaute normal schreiben.