Rasepi Blog

Leser und Schreiber befinden sich in unterschiedlichen Denkmodi. Warum bietet ihnen jedes Tool die gleiche Benutzeroberfläche?

2026-04-03T00:00:00Z

Öffne jetzt Confluence und suche ein Dokument, das du lesen musst. Was siehst du?

Eine Symbolleiste. Schaltflächen zum Bearbeiten. Kommentarfelder. Links zum Seitenverlauf. Eine Seitenleiste voller Navigation, die du nicht brauchst. Brotkrümel. Metadatenfelder. Genehmigungsanzeigen. Eine komplette Autorenoberfläche, die sich um den Text dreht, den du lesen willst.

Überlege dir jetzt, was du eigentlich wolltest: die Antwort auf eine Frage, die nächsten drei Schritte in einem Prozess oder eine Richtlinie, die du vor einem Meeting in zehn Minuten nachschlagen musst.

Du bist gekommen, um zu konsumieren. Die Benutzeroberfläche geht davon aus, dass du gekommen bist, um zu erstellen.

Das ist der Standard bei fast allen Dokumentationsplattformen. Confluence, Notion, SharePoint, GitBook, Nuclino, Slite. Sie alle bieten Lesern und Schreibern die gleiche Umgebung. Die Seite ist die Seite. Jeder erhält die gleiche Ansicht, abgesehen von ein paar Schaltflächen mit Berechtigungen.

Es fühlt sich normal an, weil wir noch nie etwas anderes hatten. Aber es ist eine Designentscheidung, kein Naturgesetz. Und es ist die falsche Entscheidung.

Die gleiche Schnittstelle für Lesen und Schreiben schafft kognitiven Overhead](/de/blog/img/readers-writers-ui.svg)

Lesen und Schreiben sind nicht dieselbe kognitive Aufgabe

Das ist keine Vorliebe für die Benutzeroberfläche. Es ist ein grundlegender Unterschied in der Arbeitsweise des Gehirns.

Wenn du schreibst, befindest du dich im generativen Modus. Du konstruierst, organisierst, entscheidest, was du einfügst und was du weglässt. Du brauchst Werkzeuge: Formatierungsoptionen, Strukturkontrollen, Medieneinbettung, Metadatenfelder, Versionsgeschichte, Funktionen zur Zusammenarbeit. Die Schnittstelle sollte dir Macht und Flexibilität geben.

Wenn du liest, bist du im rezeptiven Modus. Du scannst, filterst, nimmst das Relevante heraus und versuchst, weiterzulesen. Du brauchst Klarheit: saubere Typografie, konzentriertes Layout, minimale Ablenkung. Die Benutzeroberfläche sollte dir nicht im Weg sein.

Die Kognitionspsychologie hat dafür einen klaren Rahmen. Die [Cognitive Load Theory] (https://www.instructionaldesign.org/theories/cognitive-load/), die von John Sweller in den späten 1980er Jahren entwickelt wurde, unterscheidet zwischen intrinsischer Belastung (die Schwierigkeit des Stoffes selbst), germane Belastung (die Anstrengung des Lernens und der Integration) und extraneaner Belastung (alles, was die Umgebung hinzufügt und nicht hilfreich ist). Jede Symbolleiste, jede Seitenleiste und jede Bearbeitungsschaltfläche, die ein Leser sieht, ist überflüssig. Sie helfen dem Leser nicht, den Inhalt zu verstehen. Sie konkurrieren aktiv um die Aufmerksamkeit.

Eine Studie von Mayer und Moreno (2003) über multimediales Lernen hat gezeigt, dass die Reduzierung überflüssiger Elemente sowohl das Verständnis als auch das Behalten verbessert. Ihr Kohärenzprinzip ist direkt: Menschen lernen besser, wenn überflüssiges Material ausgeschlossen und nicht hinzugefügt wird. Eine Dokumentationsoberfläche, die dem Leser bei jedem Seitenaufruf die Steuerelemente des Autors zeigt, verstößt gegen dieses Prinzip.

Der Leser muss die Werkzeuge des Autors nicht sehen. Sie trotzdem zu zeigen, ist nicht neutral. Es ist aktiv schädlich für das Verstehen.

Wie aktuelle Plattformen dies handhaben (meistens nicht)

Schauen wir uns an, was es gibt.

Confluence hat einen Lesemodus und einen Bearbeitungsmodus, aber der Lesemodus ist immer noch von der Navigation, den Metadaten und dem Seitenbaum der Plattform umgeben. Die Bearbeitungssymbolleiste verschwindet, wenn du nicht bearbeitest, aber der mentale Rahmen "dies ist eine bearbeitbare Wikiseite" verschwindet nie ganz. Jeder Leser sieht die Schaltfläche "Bearbeiten". Die Seite flüstert: Du könntest das ändern.

Notion ist in dieser Hinsicht noch schlimmer. Der Kern der Designphilosophie ist, dass alles immer bearbeitbar ist. Klicke irgendwo und du tippst. Das ist genial für Autoren. Für Leserinnen und Leser, die den Inhalt einfach nur aufnehmen wollen, ohne Angst haben zu müssen, dass sie aus Versehen etwas ändern, ist es schrecklich. Die [Vorlagengalerie] (https://www.notion.com/templates) von Notion zeigt das: Jede Vorlage ist ein Arbeitsbereich, keine Veröffentlichung.

SharePoint unterstützt technisch gesehen verschiedene Seitenlayouts für die Anzeige und Bearbeitung, aber das Gesamterlebnis ist immer noch ein Unternehmensintranet. Die Leserinnen und Leser haben das Gefühl, dass sie sich in einem Unternehmenstool befinden und nicht in einem für das Verständnis optimierten Dokument.

GitBook kommt mit seiner sauberen, dokumentationsähnlichen Ausgabe einem Leseerlebnis am nächsten. Aber auch hier wird davon ausgegangen, dass der Leser ein Entwickler ist, der sich technische Dokumente ansieht. Es ist nicht für den allgemeinen Wissenskonsumenten gedacht.

Keine dieser Plattformen behandelt das Lesen als eine grundlegend andere Aktivität als das Schreiben. Sie behandeln es als Schreiben mit ausgeblendeter Symbolleiste.

Die Kosten einer einzigen Schnittstelle

Das ist nicht nur ein Problem der Ästhetik. Es hat messbare Konsequenzen.

Die Informationsflut verringert das Verstehen

Eine im Journal of Consumer Research veröffentlichte Studie fand heraus, dass Informationsüberlastung zu einer schlechteren Entscheidungsqualität führt, wobei der Effekt mit dem Verhältnis von irrelevanten zu relevanten Informationen zunimmt. Eine Dokumentationsseite mit sichtbaren Steuerelementen, Navigationsbäumen und Metadatenfeldern erhöht dieses Verhältnis für jeden Leser, der nicht zum Schreiben da ist.

Context Switching hat einen echten Preis

Wenn ein Interface signalisiert: "Du kannst das bearbeiten", aktiviert es einen anderen kognitiven Rahmen als "Lies das." [Gloria Marks Forschung an der UC Irvine (https://www.ics.uci.edu/~gmark/) über Aufmerksamkeit und Multitasking hat ergeben, dass es durchschnittlich 23 Minuten und 15 Sekunden dauert, bis man sich nach einem Kontextwechsel wieder voll konzentriert. Ein Leser, der kurz darüber nachdenkt, etwas zu bearbeiten (selbst um einen Tippfehler zu korrigieren), wurde aus dem Lesemodus gerissen. Das ist keine hypothetische Annahme. Jeder, der Notion benutzt hat, kennt die Erfahrung, wenn man auf einen Text klickt, um ihn auszuwählen, und dann versehentlich anfängt zu tippen.

Leser und Schreiber haben unterschiedliche Bedürfnisse an denselben Inhalt

Ein Autor muss die Struktur, Formatierungsmarkierungen, Blocktypen, Metadaten und Signale für die Zusammenarbeit sehen. Sie brauchen die ganze Maschinerie.

Ein Leser braucht sauberen Text, eine klare Hierarchie und den schnellsten Weg zu den gesuchten Informationen. Sie brauchen den Inhalt, nicht die Maschinerie.

Werden beide über dieselbe Schnittstelle bedient, bedeutet das, dass keiner von ihnen ein für seine eigentliche Tätigkeit optimiertes Erlebnis hat.

Und dann ist da noch die dritte Zielgruppe: KI

Hier wird es kompliziert, und die bestehenden Plattformen sind völlig unvorbereitet.

Die Dokumentation im Jahr 2026 hat drei verschiedene Verbraucher, nicht zwei:

Autoren, die Inhalte erstellen und pflegen
Leser, die Inhalte visuell konsumieren
KI-Systeme, die Inhalte programmgesteuert abrufen, analysieren und zusammenstellen

Jedes dieser Zielgruppen braucht eine grundsätzlich andere Schnittstelle zu denselben zugrunde liegenden Inhalten.

Autoren brauchen umfangreiche Bearbeitungswerkzeuge, Funktionen zur Zusammenarbeit und strukturelle Kontrollen. Leser brauchen eine übersichtliche, konzentrierte Darstellung mit minimaler Ablenkung. KI braucht eine strukturierte, maschinenlesbare Ausgabe mit expliziten Metadaten: Aktualitätssignale, Klassifizierungskennzeichen, Adressierung auf Blockebene und saubere semantische Markups.

Wie wir in Builders, Not Developers erörtert haben, sind KI-Vermittler bereits der dominierende Konsument von Dokumentation für einen wachsenden Teil der Wissensarbeiter. Die [GitHub-Entwicklerumfrage 2024] (https://github.blog/news-insights/research/survey-ai-wave-grows/) ergab, dass 97 % der Entwickler in Unternehmen KI-Codierwerkzeuge verwenden. Bis 2026 werden 84% der Entwickler regelmäßig KI-Tools nutzen, wobei 41% des gesamten Codes durch KI generiert werden.

Diese KI-Systeme interessieren sich nicht für deine Seitenleiste oder deine Symbolleiste. Sie brauchen saubere Daten. Und eine Plattform, die die Lesersicht mit der Autorensicht verwechselt, verwechselt auch die von der KI konsumierbare Oberfläche mit der Oberfläche des menschlichen Verfassers. Das sind drei Unstimmigkeiten in einer Schnittstelle.

Drei Zielgruppen, drei unterschiedliche Bedürfnisse](/de/blog/img/readers-writers-three-audiences.svg)

Wie Rasepi die Erfahrungen trennt

Rasepi basiert auf dem Prinzip, dass das Erstellen von Inhalten und das Konsumieren von Inhalten unterschiedliche Aktivitäten sind, die unterschiedliche Schnittstellen verdienen.

Die Umgebung des Autors

Wenn du in Rasepi schreibst, bekommst du eine vollständige Autorenumgebung. Rich-Text-Editing mit TipTap, Steuerelemente auf Blockebene, Übersetzungsstatusanzeigen, Ablaufmanagement, Tools für die Zusammenarbeit, Ansichten für die Inhaltsstruktur und alles andere, was ein Autor braucht, um qualitativ hochwertige Dokumentation zu erstellen und zu pflegen.

Der Autor sieht die Maschinerie, weil er die Maschinerie braucht.

Die Umgebung des Lesers

Wenn jemand ein Rasepi-Dokument konsumiert, sieht er ein sauberes, konzentriertes Leseerlebnis. Kein Bearbeitungs-Chrome. Keine Symbolleisten. Keine "Du kannst das ändern"-Signale. Nur der Inhalt, der in einem Layout präsentiert wird, das für das Verstehen und Überfliegen optimiert ist.

Der Leser sieht die Schaltfläche "Bearbeiten" nicht, denn er ist nicht hier, um zu bearbeiten. Er ist hier, um etwas zu lernen, einen Prozess zu verfolgen oder eine Antwort zu finden. Die Benutzeroberfläche respektiert diese Absicht.

Die KI-Oberfläche

Für KI-Konsumenten stellt Rasepi Inhalte über strukturierte APIs mit vollständigen Metadaten zur Verfügung. Jeder Block enthält einen Freshness Score, einen Übersetzungsstatus, einen Content Hash und Klassifizierungskennzeichen. KI-Systeme können Inhalte auf Blockebene abfragen, nach Aktualität filtern, veraltetes Material oder Entwürfe ausschließen und genau die strukturierten Daten abrufen, die sie benötigen.

Kein Scraping einer Wikiseite und Hoffen auf das Beste. Die KI erhält eine speziell entwickelte Schnittstelle, genau wie der Leser und der Autor.

Eine Inhaltsebene, drei Schnittstellen

Das Wichtigste ist, dass wir nicht drei Kopien des Inhalts verwalten. Das ist nicht das Problem der fünf Kopien des Onboardings, das wir in Stop Maintaining Five Copies of the Same Document besprochen haben.

Es handelt sich um eine Inhaltsebene, die in strukturierten Blöcken gespeichert ist und über drei verschiedene Ansichten für drei verschiedene Zielgruppen optimiert wird.

Der Autor bearbeitet die Blöcke. Der Leser sieht zusammengestellte, gestylte Inhalte. Die KI fragt strukturierte Daten mit Metadaten ab. Dieselben Blöcke. Dieselbe Quelle der Wahrheit. Unterschiedliche Präsentationsschicht für jeden Verbraucher.

Dies ist nur aufgrund der Architektur auf Blockebene möglich. Jeder Inhalt ist eine individuell adressierbare Einheit mit eigenen Metadaten. Du kannst diese Blöcke unterschiedlich präsentieren, je nachdem, wer nach ihnen fragt:

Zielgruppe	Bedürfnisse	Gets
Writer	Formatierung, Struktur, Zusammenarbeit, Metadaten	Vollständige Authoring-Umgebung mit Kontrollen auf Blockebene
Leser	Sauberer Text, klare Hierarchie, schnelles Scannen	Fokussierte Leseansicht, kein Bearbeitungs-Chrome
AI	Strukturierte Daten, Freshness Scores, Klassifizierung	Block-Level-API mit vollständigen Metadaten

Warum das wichtiger ist, als es aussieht

Du liest das vielleicht und denkst: "Das ist nur UI. Verschiedene Ansichten der gleichen Sache. Wie wichtig kann das schon sein?"

Sehr wichtig, wie sich herausstellt.

Leservertrauen

Menschen vertrauen Inhalten, die veröffentlicht aussehen. Wenn eine Seite wie ein Wiki aussieht, das jeder bearbeiten kann, wird sie von den Lesern unbewusst abgelehnt. Wenn derselbe Inhalt in einer sauberen, veröffentlichungsreifen Ansicht präsentiert wird, hat er mehr Autorität. Das ist nicht irrational. Es ist ein Zeichen dafür, dass jemand die Präsentation ernst genommen hat, was bedeutet, dass er auch den Inhalt ernst genommen hat.

Die Nielsen Norman Group hat dies eingehend untersucht. Ihre [Studie zur Glaubwürdigkeit von Inhalten] (https://www.nngroup.com/articles/trust-signals-content/) zeigt, dass die Qualität des Designs und der Präsentation zu den stärksten Signalen gehören, anhand derer die Nutzer die Vertrauenswürdigkeit von Inhalten beurteilen. Eine unübersichtliche Editoransicht untergräbt aktiv die Glaubwürdigkeit der angezeigten Inhalte.

Produktivität des Autors

Autoren, die in einer speziellen Autorenumgebung arbeiten, müssen nicht zwischen den Kontexten "lese ich oder schreibe ich?" hin und her wechseln. Die Werkzeuge sind da, weil sie da sein sollen, und nicht, weil die Benutzeroberfläche nicht entscheiden konnte, wer auf sie schaut.

KI-Zuverlässigkeit

Wenn KI-Systeme über eine speziell entwickelte Oberfläche mit strukturierten Metadaten verfügen, können sie besser entscheiden, was sie abrufen und was sie ausschließen. Sie können Freshness-Scores überprüfen, bevor sie einen Block in eine Antwort aufnehmen. Sie können Klassifizierungskennzeichen beachten. Sie können nach Sprache, Status oder Zielgruppe filtern. All das ist nicht möglich, wenn die KI dieselbe HTML-Seite ausliest, die für menschliche Leser konzipiert wurde.

Der Wechsel des mentalen Modells

Die Grundannahme der meisten Dokumentationsplattformen ist: die Seite ist die Einheit, und jeder interagiert mit der Seite.

Rasepi geht von einer anderen Annahme aus: Der Block ist die Einheit, und verschiedene Zielgruppen interagieren mit den Blöcken durch speziell entwickelte Oberflächen.

Das klingt wie ein kleiner architektonischer Unterschied. Ist es aber nicht. Es ist der Unterschied zwischen einem Werkzeug, das KI-Systemen zufällig Inhalte zeigt, und einem, das sie absichtlich bedient. Zwischen einer Schreibumgebung, die zufällig lesbar ist, und einem Leseerlebnis, das von Grund auf neu entwickelt wurde. Zwischen einer guten Schnittstelle und drei großartigen.

Dokumentation wird nicht mehr nur geschrieben und gelesen. Sie wird geschrieben, gelesen, abgefragt, übersetzt, bewertet, klassifiziert und in großem Umfang an KI-Systeme weitergegeben. Wenn wir so tun, als ob wir das könnten, haben wir Wikis, die niemand lesen will, und KI-Assistenten, die Antworten von Seiten abrufen, die nie dafür gedacht waren, maschinell verarbeitet zu werden.

Leser und Schreiber befinden sich in unterschiedlichen Denkmodi. Die KI ist in einem ganz anderen Modus. Die Benutzeroberfläche sollte das widerspiegeln.

The State of Docs in 2026: Fünf Trends, die die nächste Ära bestimmen werden

2026-04-03T00:00:00Z

Alle paar Monate nehme ich mir einen Vormittag Zeit, um einfach nur zu lesen. Nicht Rasepi-Code, nicht GitHub-Probleme. Blogs von Mitbewerbern, Branchenberichte, Ankündigungen von Keynotes, Umfragen unter Entwicklern. Alles, was im letzten Quartal veröffentlicht wurde und mit Dokumentation, Wissensmanagement oder KI-gestützten Workflows zu tun hat.

Das habe ich letzte Woche getan, und das Bild, das sich dabei ergab, war schärfer als erwartet. Nicht, weil eine einzelne Ankündigung bahnbrechend war, sondern weil fünf verschiedene Trends zusammenlaufen, die zusammengenommen ein klares Bild davon zeichnen, was Dokumentationsplattformen in den nächsten zwei Jahren leisten müssen.

Hier ist, was ich gefunden habe.

1. KI ist jetzt der wichtigste Leser. Nicht der Mensch.

GitBook hat in seinem [AI docs data report] (https://www.gitbook.com/blog/ai-docs-data-2025) eine beeindruckende Zahl veröffentlicht: Die KI-Leserschaft von Dokumentationen stieg 2025 um über 500%. Fünfhundert Prozent. Das ist kein Rundungsfehler.

Die 2024 Developer Survey von Stack Overflow zeigt, dass 61% der Entwickler/innen mehr als 30 Minuten pro Tag mit der Suche nach Antworten verbringen. Aber die Art und Weise, wie sie suchen, hat sich verändert. GitHubs eigene Umfrage ergab, dass 97% der Unternehmensentwickler KI-Coding-Tools verwenden. Im Jahr 2026 werden 84% der Entwickler täglich KI-Tools verwenden, wobei 41% des Codes inzwischen von KI generiert wird. Diese Leute navigieren nicht durch die Seitenleiste deines Wikis. Sie fragen Claude oder Copilot, und die KI liest deine Dokumente in ihrem Namen.

Die Auswirkungen sind kaum zu überschätzen. Dein häufigster Dokumentationskonsument ist nicht mehr eine Person, die einen Browser-Tab geöffnet hat. Es ist ein Sprachmodell, das Suchanfragen stellt. Und dieses Modell ist nicht in der Lage, auf eine Seite zu schielen und zu denken: "Hm, das sieht veraltet aus."

GitBook hat das früh erkannt und mit seinem [State of Docs 2026 report] (https://www.gitbook.com/blog/state-of-docs-2026) und einem Vorstoß in Richtung maschinenlesbare Formate reagiert. Außerdem haben sie [skill.md] (https://www.gitbook.com/blog/skill-md) veröffentlicht, eine Konvention zur Strukturierung von Produktinformationen speziell für KI-Agenten. Google ging mit seinem Gemini API Docs MCP noch weiter, das Kodieragenten über das Model Context Protocol mit der aktuellen Dokumentation verbindet. Die Argumentation war eindeutig: Agenten erzeugen veralteten Code, weil ihre Trainingsdaten ein Stichtag sind. Mit der MCP-Lösung stieg die Erfolgsquote auf 96,3 %.

Der erste Trend ist also bestätigt. KI ist der wichtigste Leser. Die Plattformen, die dies als eine zentrale Designvorgabe behandeln und nicht als eine Funktion, die später hinzugefügt werden kann, werden einen strukturellen Vorteil haben.

2. Frische und vertrauenswürdige Metadaten werden zur Pflicht

Anthropic befragte [81.000 Claude-Nutzer] (https://www.anthropic.com/81k-interviews) im Dezember 2025 und veröffentlichte die Ergebnisse im März 2026. Es ist die größte qualitative Studie über KI-Nutzer, die jemals durchgeführt wurde (159 Länder, 70 Sprachen). Die meistgenannte Sorge? Die Unzuverlässigkeit. 27% der Befragten nannten sie als ihre größte Sorge und 79% dieser Menschen haben sie am eigenen Leib erfahren.

Diese Zahl sollte jedes Dokumentationsteam nachts wach halten.

Wenn KI-Antworten unzuverlässig sind, liegt das Problem nicht immer am Modell. Oft gibt das Modell getreu wieder, was es in einem veralteten Dokument gefunden hat. Das Modell hat nicht halluziniert. Deine Dokumente waren einfach falsch, und niemand hat sie gemeldet.

Die Daten von Stack Overflow untermauern dies aus einem anderen Blickwinkel: 81% der Entwickler erwarten, dass KI im kommenden Jahr stärker in die Art und Weise, wie sie Code dokumentieren, integriert wird. Wenn 81 % deiner Nutzer/innen die KI mit Dokumenten füttern und 27 % der KI-Nutzer/innen die Unzuverlässigkeit als größtes Problem bezeichnen, hast du ein Vertrauensproblem, das keine noch so prompte Entwicklung beheben kann. Die Lösung liegt an der Quelle.

Deshalb sind Metadaten zur Aktualität so wichtig. Nicht der Zeitstempel "zuletzt bearbeitet" (er sagt aus, wann jemand die Datei angefasst hat, und nicht, ob der Inhalt noch aktuell ist). Echte Aktualität: Überprüfungsstatus, Linkstatus, Übersetzungsabgleich, Lesersignale, Erkennung von Inhaltsabweichungen. Metadaten, die eine Maschine lesen und nutzen kann, um zu entscheiden, ob ein Dokument sicher zitiert werden kann.

Ich komme immer wieder auf eine einfache Formulierung zurück. Deine Dokumentation braucht einen Credit Score. Nicht einen Zeitstempel. Eine Kreditwürdigkeit. (Wir haben genau das mit dem Frische-Scoring-System von Rasepi entwickelt, und wenn ich mir die Daten aus der Branche ansehe, bin ich noch mehr davon überzeugt, dass es die richtige Entscheidung ist).

3. Die Übersetzung wird von "Projekt" auf "Pipeline" umgestellt

DeepL veröffentlichte im Februar einen Artikel mit dem Titel ["The 6 Translation Transformations Global Businesses Can't Afford to Miss"] (https://www.deepl.com/en/blog/six-translation-transformations). Ihr Argument: Übersetzung wird zu einer kontinuierlichen betrieblichen Herausforderung, nicht zu einem vierteljährlichen Stapelprojekt.

Das deckt sich mit allem, was ich sehe.

Das alte Modell war ganz einfach. Schreibe auf Englisch. Wenn du ein gewisses Budget hast, engagiere einen Übersetzer oder beauftrage einen Übersetzungsdienst. Erhalte die Übersetzungen zurück. Lade sie hoch. Erledigt bis zum nächsten Mal. Das Problem ist, dass das "nächste Mal" immer schneller kommt, wenn dein Produkt wöchentlich ausgeliefert wird und deine Dokumente ständig aktualisiert werden. Bis die deutsche Version von der Überprüfung zurück ist, hat sich der englische Quelltext bereits zweimal geändert.

Der [Customization Hub] (https://www.deepl.com/customization-hub) von DeepL bietet jetzt Glossare, Stilregeln und Formalitätseinstellungen, was großartig ist. Aber wenn diese Tools außerhalb deiner Dokumentationsplattform liegen, musst du eine ganze Übersetzungs-Toolchain verwalten: Editor, Export, Übersetzung, Überprüfung, Reimport, Wiederholung. Jeder Schritt birgt die Gefahr, dass du abweichst.

Notion hat keine native mehrsprachige Unterstützung. Confluence bietet sie über Marketplace-Plugins an. GitBook [fügte die automatische Übersetzung im August 2025 hinzu] (https://www.gitbook.com/blog/new-in-gitbook-august-2025), das ist ein Schritt, aber er funktioniert auf Seitenebene.

Die wirkliche Veränderung ist der Wechsel von der Seitenebene zur Blockebene. Wenn du die Übersetzungen auf der Absatzebene verfolgst, übersetzst du nur das, was sich tatsächlich geändert hat. Bei einer typischen Bearbeitung werden vielleicht zwei von vierzig Absätzen geändert. Das sind 94 % weniger Übersetzungsarbeit. (Das ist der Kern von Rasepis Übersetzungsarchitektur und ehrlich gesagt das, worauf ich bei dem Produkt am meisten stolz bin. Aber selbst wenn man uns beiseite lässt, ist die Richtung klar: Kontinuierliche, inkrementelle, eingebettete Übersetzung ist die Richtung, in die es geht).

4. KI-Agenten brauchen strukturierte Inhalte, keine Wikiseiten

Das hat sich für mich herauskristallisiert, als Notion im Februar [Custom Agents] (https://www.notion.com/blog/introducing-custom-agents) ankündigte. 21.000 Agenten wurden während des frühen Zugangs gebaut. Agenten, die Fragen aus Wissensdatenbanken beantworten, Aufgaben weiterleiten und Statusberichte erstellen. Allein Ramp hat über 300 Agenten.

Atlassian ging in eine ähnliche Richtung. [Rovo AI in Confluence] (https://www.atlassian.com/blog/confluence/create-and-edit-with-rovo) zieht Kontext aus allen Anwendungen von Atlassian und Drittanbietern, um Inhalte zu erstellen. Ihr Argument: "Kontextreiche, qualitativ hochwertige Inhalte, die auf der bestehenden Arbeit deines Teams basieren".

Und dann hat Anthropic Agententeams in Claude Code entwickelt, bei dem mehrere KI-Agenten komplexe Aufgaben selbstständig koordinieren. Opus 4.6 erreicht 76 % beim 8-Nadel 1M MRCR Benchmark (gegenüber 18,5 % beim Vorgängermodell), d. h. es kann tatsächlich Informationen aus riesigen Dokumentenmengen abrufen, ohne den Überblick zu verlieren.

Alle drei Unternehmen entwickeln Agenten, die Dokumente auswerten. Keines von ihnen hat das Problem der Quellenqualität gelöst.

In der Dokumentation der Custom Agents von Notion wird ausdrücklich auf das Prompt Injection Risk hingewiesen, wenn Agenten nicht vertrauenswürdige Inhalte lesen. Rovo von Atlassian liest alles, was es in deinem Confluence findet. Wenn dieser Inhalt drei Monate alt ist, weiß Rovo das nicht. Er baut trotzdem darauf auf.

Damit Agenten zuverlässig arbeiten können, brauchen sie mehr als nur Textseiten. Sie brauchen strukturierte Inhalte mit stabilen Bezeichnern, eindeutigen Aktualitätssignalen, klaren Klassifizierungsmetadaten und der Möglichkeit, zwischen "das ist aktuell und geprüft" und "das gibt es, aber niemand hat es seit einem Jahr angefasst" zu unterscheiden. Wiki-Seiten bieten das nicht. Strukturierte Inhalte auf Blockebene mit vertrauenswürdigen Metadaten schon.

5. Open Source und Self-Hosting erleben ein Comeback

Der letzte Punkt ist eher ein Bauchgefühl, das durch Daten gestützt wird, als eine einzelne Ankündigung.

GitBook [hat seine veröffentlichte Dokumentation] (https://www.gitbook.com/blog/free-open-source-documentation) Ende 2024 als Open Source veröffentlicht und einen OSS-Fonds eingerichtet. Die Begründung: Open-Source-Projekte verdienen kostenlose, hochwertige Dokumentationswerkzeuge. Aber der Schritt ist auch ein Zeichen für etwas Größeres.

Notion ist ein reines Cloud-Angebot. Es gibt keine selbstgehostete Option. Das Confluence Data Center ist zwar vorhanden, erfordert aber eine Lizenz. Wenn deine Dokumentationsplattform dein sensibelstes betriebliches Wissen enthält (Playbooks für Vorfälle, Compliance-Verfahren, Architekturentscheidungen), ist die Frage, wer diese Daten kontrolliert, nicht abstrakt.

Der Beitrag von Anthropic ["Claude is a space to think"] (https://www.anthropic.com/news/claude-is-a-space-to-think) vom Februar enthält ein interessantes Argument über Vertrauen und Geschäftsmodelle. Ihre Kernaussage: Werbeanreize sind unvereinbar mit einem wirklich hilfreichen KI-Assistenten. Sie haben sich dafür entschieden, werbefrei zu bleiben, damit die Nutzer dem Tool vertrauen können.

Ich denke, es gibt eine Parallele für Dokumentationsplattformen. Wenn dein Dokumentsystem ein Closed-Source-System ist und nur in der Cloud läuft, kannst du nicht überprüfen, was es an die KI weitergibt. Du kannst die Berechnung der Aktualität nicht überprüfen. Du kannst nicht sicherstellen, dass deine Daten unter deiner Kontrolle bleiben. Für Teams, die KI-Assistenten auf ihre Wissensdatenbank aufsetzen (und das tun zunehmend alle), ist die Überprüfbarkeit wichtig.

Dies ist keine Polemik darüber, dass Open Source moralisch überlegen ist. Closed-Source-Produkte können durchaus vertrauenswürdig sein. Aber wenn du KI-gestützte Workflows auf deiner internen Dokumentation aufbaust, ist die Möglichkeit, das System zu prüfen und zu verifizieren, ein praktischer Vorteil. Für uns war die MIT-Lizenzierung von Rasepi kein nachträglicher Einfall. Es war eine Designentscheidung, die auf derselben Logik beruht: Die Dokumentationsinfrastruktur sollte überprüfbar sein.

Was diese fünf Trends zusammen bedeuten

Für sich genommen ist jeder dieser Trends überschaubar. KI liest deine Dokumente? Okay, füge ein paar maschinenlesbare Metadaten hinzu. Frische ist wichtig? Gut, füge Überprüfungsdaten hinzu. Die Übersetzung muss kontinuierlich erfolgen? Klar, integriere DeepL. Agenten brauchen Struktur? Gut, verbessere dein Inhaltsmodell. Souveränität ist wichtig? Gut, biete eine selbst gehostete Option an.

Aber zusammengenommen beschreiben sie eine Plattform, die sich grundlegend von dem unterscheidet, was die meisten Teams heute nutzen.

Der Unterschied liegt in der Architektur. Es handelt sich nicht um fünf Funktionen, die man anbauen kann. Es sind fünf Annahmen, die in das Fundament eingebaut werden müssen. Wie die Inhalte gespeichert werden (auf Blockebene, nicht auf Seitenebene). Wie das Vertrauen modelliert wird (Freshness Scores, nicht Zeitstempel). Wie die Übersetzung funktioniert (inkrementell, eingebettet, pro Absatz). Wie KI-Agenten auf Inhalte zugreifen (strukturierte APIs mit Metadaten, keine Seitenabfragen). Wie die Daten kontrolliert werden (offen, überprüfbar, selbst-hostbar).

Keine etablierte Plattform wurde für alle fünf Punkte gleichzeitig entwickelt. Einige fügen sie Stück für Stück hinzu. GitBook ist bei der KI-Lesbarkeit am weitesten fortgeschritten. Notion baut eine Agenteninfrastruktur auf. Atlassian hat eine Enterprise Distribution.

Aber vom ersten Tag an für alle fünf entwickeln? Das ist der Vorteil, wenn man ganz neu anfängt, wenn sich das Terrain verschiebt.

Ich weiß, dass ich hier voreingenommen bin. Wir haben Rasepi entwickelt, weil wir sahen, dass diese Trends zusammenlaufen und wir wollten eine Plattform, die von Anfang an alle diese Trends berücksichtigt. Übersetzung auf Blockebene, erzwungenes Verfallsdatum, Freshness Scoring, strukturierte KI-kompatible Inhalte, Open Source. Das ist die These des ganzen Projekts.

Aber selbst wenn es uns nicht gäbe, denke ich, dass jede ehrliche Betrachtung dessen, was im ersten Quartal 2026 passiert, in dieselbe Richtung weist. Die Dokumentation wird zur Infrastruktur. Und Infrastruktur hat andere Anforderungen als Wikiseiten.

Die Teams, die das zuerst herausfinden, werden nicht nur bessere Dokumentationen haben. Sie werden zuverlässigere KI-Agenten, niedrigere Übersetzungskosten, weniger Überraschungen bei der Einhaltung von Vorschriften und Wissensdatenbanken haben, die auch im Laufe der Zeit vertrauenswürdig bleiben.

Das ist der Zustand der Dokumente im Jahr 2026. Die Frage ist nicht, ob diese Trends real sind. Die Frage ist, ob deine Plattform für sie entwickelt wurde.

Fünf Trends. Eine architektonische Frage: Wurde deine Dokumentationsplattform für das Jahr 2026 entwickelt oder bedient sie immer noch Annahmen aus dem Jahr 2016?

Quellen: GitBook AI docs data report, GitBook State of Docs 2026, GitBook skill.md, Google Gemini API Docs MCP, Stack Overflow 2024 Developer Survey, GitHub 2024 developer survey, Index.dev developer productivity statistics, Anthropic "What 81,000 People Want from AI", Anthropic "Claude is a space to think", Claude Opus 4.6, Notion Custom Agents, Atlassian Rovo in Confluence, DeepL "6 Translation Transformations", DeepL Customization Hub, GitBook open source documentation, GitBook auto-translate.

Erbauer, nicht Entwickler: Wie Claude verändert hat, für wen deine Docs bestimmt sind

2026-04-02T00:00:00Z

Irgendwo in diesem Moment gibt es eine Person, die deine API integriert. Sie sind nicht auf deiner Dokumentationsseite. Sie hat deinen Leitfaden für die ersten Schritte nicht geöffnet. Sie haben noch nie deine interaktive Spielwiese oder deine sorgfältig gestaltete Seitennavigation gesehen.

Sie sitzen in Claude. Oder Copilot. Oder Cursor. Sie tippen etwas ein wie "integriere die Stripe Billing API mit meiner Next.js App unter Verwendung des App-Routers" und warten darauf, dass funktionierender Code zurückkommt. Die KI hat deine Dokumente für dich gelesen. Sie fand die relevanten Endpunkte, verstand den Authentifizierungsfluss, wählte die richtigen SDK-Methoden und erstellte eine Implementierung.

Vor zwei Wochen, beim Start Summit Hackathon in St. Gallen, konnte ich dies in Echtzeit beobachten. Ich unterhielt mich mit einer Gruppe von CS-Studenten und ein paar Startup-Gründern darüber, wie sie an neue APIs herangehen, und jeder von ihnen beschrieb denselben Arbeitsablauf: Das Problem in eine KI einfügen, Code zurückbekommen, von dort aus iterieren. Eine der Studentinnen lachte, als ich sie fragte, ob sie die Dokumente gelesen hätte. "Warum sollte ich? Claude liest sie für mich."

Die Person hat deine Website nie besucht. Sie wird deine Seite vielleicht nie besuchen. Und genau so wird Software zunehmend entwickelt.

Die Kernverschiebung

Die Dokumentation hat heute zwei grundverschiedene Abnehmer: Menschen, die sie lesen, und KI-Assistenten, die sie im Auftrag von Entwicklern lesen. Die meisten Dokumentationen sind ausschließlich für Menschen optimiert. Die KI ist bereits der dominierende Leser.

Das verändert alles nachgelagerte Bereiche:

Frische Inhalte sind jetzt eine Frage der Zuverlässigkeit. Wenn eine KI veraltete Inhalte serviert, hat der Ersteller keine Möglichkeit, das Problem zu erkennen. Der Schaden wächst stillschweigend mit.
"Entwickler" ist ein zu eng gefasster Begriff. Produktmanager, Designer und Analysten liefern Software über KI-Assistenten aus, oft ohne jemals selbst eine Zeile der Dokumentation gelesen zu haben.
Maschinenlesbare Struktur ist wichtiger als visuelles Design. Sauberes Markdown, in sich geschlossene Blöcke und explizite Metadaten ermöglichen es der KI, dein Produkt korrekt darzustellen.
Die Anforderungen an das Format haben sich aufgeteilt. Menschliche Leser brauchen Erzählungen. KI-Vermittler brauchen strukturierte, analysierbare Spezifikationen. Du musst beide bedienen.

Der Rest dieses Beitrags erklärt, wie es dazu kam, was das für DevRel bedeutet und was du jetzt tun kannst.

Die Reise, die niemand geplant hat

Lange Zeit folgten die Beziehungen zwischen Entwicklern einem wohlverstandenen Weg. Du hast umfassende Dokumentationen geschrieben. Du hast Schnellstartanleitungen veröffentlicht. Du hast auf Konferenzen Vorträge gehalten. Du hast eine Präsenz auf Stack Overflow unterhalten. Du hast deine API-Referenz durchsuchbar gemacht, deine SDKs idiomatisch und deine Fehlermeldungen hilfreich.

Dieser Weg setzt voraus, dass die Entwickler deine Inhalte lesen. Navigiere durch deine Struktur. Folge deinen Schritten.

[Die GitHub-Entwicklerumfrage 2024 (https://github.blog/news-insights/research/survey-ai-wave-grows/) ergab, dass 97 % der Entwickler in Unternehmen schon einmal KI-Tools verwendet haben. [Die jährliche Umfrage von Stack Overflow (https://survey.stackoverflow.co/2024/) ergab, dass 76 % aller Entwickler/innen KI-Tools nutzen oder planen, sie zu nutzen, wobei 62 % der Fachleute sie aktiv im Alltag einsetzen. Bis 2026 steigt diese Zahl auf 84 %, wobei 41 % des gesamten Codes inzwischen von KI generiert werden und 51 % der professionellen Entwickler/innen KI-Tools täglich nutzen. Diese Zahlen werden sich nicht abschwächen.

Die neue Reise sieht anders aus. Jemand beschreibt in natürlicher Sprache, was er will. Ein KI-Assistent liest die Dokumentation, findet die relevanten Abschnitte und erstellt die Integration. Der Builder prüft die Ergebnisse, verfeinert vielleicht die Eingabeaufforderung oder fragt nach. Das dauert nur Minuten, nicht Stunden.

Der Einstiegstrichter, an dem DevRel-Teams jahrelang gefeilt haben? Er wird übersprungen. Nicht, weil er schlecht war. Der Einstiegspunkt hat sich einfach verschoben.

Zwei Verbraucher, ein Satz Dokumente

Die Dokumentation hat jetzt zwei grundlegend verschiedene Zielgruppen.

Das erste ist der menschliche Leser. Diese Person gibt es immer noch. Sie tauchen auf, wenn es um Architekturentscheidungen, das Debuggen von Grenzfällen, die Überprüfung der Einhaltung von Vorschriften und das Verständnis von Konzepten geht. Sie wollen erzählende Erklärungen, gut organisiertes Referenzmaterial und klare Argumente für Kompromisse.

Der zweite ist der KI-Vermittler. Er liest deine Dokumentation im Auftrag des Bauherrn. Sie kümmert sich nicht um deine Seitenleiste. Sie schätzt dein visuelles Design nicht. Sie braucht strukturierte, maschinenlesbare Inhalte: saubere Markdowns, konsistente Formatierungen, eindeutige Spezifikationen, über die sie ohne Mehrdeutigkeit nachdenken kann.

Fast jede Dokumentationsseite ist heute ausschließlich für die erste Zielgruppe optimiert. Die zweite Zielgruppe ist bereits der dominierende Verbraucher.

Jeremy Howard erkannte dieses Spannungsverhältnis, als er 2024 den /llms.txt-Standard vorschlug. Seine Beobachtung war präzise: "Große Sprachmodelle stützen sich zunehmend auf Website-Informationen, stoßen aber auf eine entscheidende Einschränkung: Die Kontextfenster sind zu klein, um die meisten Websites in ihrer Gesamtheit zu erfassen." Der Vorschlag ist einfach. Eine kuratierte Markdown-Datei unter /llms.txt, die den KI-Modellen einen strukturierten Überblick über dein Produkt und Links zu den wichtigsten Ressourcen gibt. FastHTML, Anthropics eigene Dokumente und ein [wachsendes Verzeichnis von Projekten] (https://llmstxt.site/) liefern jetzt eine solche Datei aus.

Das ist eine nützliche Konvention. Aber sie ist auch ein Symptom für ein tieferes Problem. Das eigentliche Problem ist nicht das Format. Das Problem ist, dass die meisten Dokumentationen nie mit Blick auf die Nutzung durch Maschinen entwickelt wurden.

Der Erbauer spart nicht am falschen Ende.

Die Versuchung ist groß, die Person, die Claude auffordert, statt die Dokumentation zu lesen, zu betrachten und daraus zu schließen, dass sie Abkürzungen nimmt. Dass sie nicht wirklich verstehen, was im Code passiert. Dass sie irgendwie eine minderwertige Art von Entwickler sind.

Ich habe dieses Gespräch schon oft genug geführt, um zu wissen, dass das meistens falsch ist.

Viele dieser Entwickler sind erfahrene Ingenieure, die sich bewusst für Effizienz entscheiden. Sie verstehen den Code, aber sie wollen nicht vier Seiten Dokumentation wälzen, um die drei Zeilen zu finden, die sie wirklich brauchen. Sie haben gelernt, dass ein KI-Assistent diese Zeilen schneller extrahieren kann, als sie sie suchen können, also delegieren sie das Lesen. (Ehrlich gesagt, mache ich das auch. Ich kann mich nicht erinnern, wann ich das letzte Mal eine Anleitung für den Einstieg von vorne bis hinten gelesen habe).

Anthropic hat dieses Muster erkannt, als sie das Model Context Protocol entwickelt haben. MCP wird inzwischen von Claude, ChatGPT, VS Code, Cursor und anderen unterstützt. Es ist explizit so konzipiert, dass KI-Assistenten auf externe Systeme zugreifen, Kontext abrufen und darauf reagieren können. In der Spezifikation heißt es, dass es _"Zugang zu einem Ökosystem von Datenquellen, Tools und Apps bietet, das die Fähigkeiten und die Erfahrung des Endnutzers verbessert".

Lies das genau. Das ist die Sprache der Infrastruktur, nicht die Sprache der Bequemlichkeit. Die Entwickler/innen, die diese Tools nutzen, vermeiden keine Arbeit. Sie arbeiten sich durch eine neue Ebene, und deine Dokumentation ist Teil dieser Ebene, ob du sie nun dafür vorgesehen hast oder nicht.

Die Zahlen belegen dies. Allein Claude verarbeitet heute [25 Milliarden API-Aufrufe pro Monat] (https://www.incremys.com/en/resources/blog/claude-statistics), mit 30 Millionen monatlich aktiven Nutzern in 159 Ländern. 70% der Fortune 100 Unternehmen nutzen Claude. Laut einer Umfrage von Menlo Ventures hält Anthropic 32 % des KI-Marktanteils in Unternehmen, gemessen an der Modellnutzung, vor OpenAI mit 25 %. Ein HSBC-Forschungsbericht beziffert den Anteil sogar noch höher: 40 % der gesamten KI-Ausgaben. Das sind keine experimentellen Tools. Sie sind die primäre Infrastruktur.

Die Beziehungen zwischen Entwicklern wurden für eine andere Zeit geschaffen.

Wenn deine DevRel-Strategie vor 2023 entwickelt wurde, war sie für eine Welt gedacht, in der Entwickler die Dokumente direkt lesen. Diese Welt ist nicht verschwunden, aber sie ist nicht mehr das vorherrschende Interaktionsmuster für einen wachsenden Anteil von Entwicklern.

Das verändert die Kalkulation einiger langjähriger DevRel-Aktivitäten.

Konferenzvorträge. Eine 45-minütige Präsentation auf einer Entwicklerkonferenz erreicht einen Raum mit ein paar hundert Leuten. Eine gut strukturierte /llms.txt-Datei und eine saubere, maschinenlesbare Dokumentation erreichen jeden Builder, der einen KI-Assistenten über dein Produkt befragt, kontinuierlich und zu jeder Zeit. Das Gespräch ist ein einmaliges Ereignis. Die maschinenlesbare Dokumentation bleibt bestehen. Ich will damit nicht sagen, dass Konferenzen wertlos sind (ich komme gerade von einer zurück), aber das Verhältnis der Hebelwirkung hat sich verschoben.

Anleitungen für den Einstieg Die klassische Schnellstart-Anleitung in fünf Schritten wird immer mehr zu einer Formalität. Die Bauherren folgen den Schritten nicht. Er beschreibt, was er will, und erwartet, dass die KI die Integration vornimmt. Wenn die API in einem maschinenfreundlichen Format gut dokumentiert ist, bewältigt die KI den Einstieg effizienter, als es ein Tutorial könnte. Tutorien sollten stattdessen konzeptionelles Material sein: Sie sollten erklären, warum du Ansatz A gegenüber Ansatz B wählst. Bei der Erklärung von Kompromissen ist sie viel weniger zuverlässig.

Stack Overflow. Ihre eigenen Umfragedaten haben gezeigt, dass 84% der Entwickler die technische Dokumentation direkt nutzen, wobei 90% von ihnen sich auf die Dokumentation in API- und SDK-Paketen verlassen. Aber die Art und Weise, wie sie auf diese Dokumente zugreifen, erfolgt zunehmend über eine KI-Ebene und nicht über einen Browser-Tab. Die Fragen, die Stack Overflow noch erreichen, sind meist die schwierigen. Grenzfälle, Debugging in der Produktion, Dinge, die Feinheiten erfordern. Wertvoll, sicher. Aber das Volumen ist nicht mehr da.

Wenn die KI deine Dokumente liest, wird die Aktualität entscheidend

Hier ist der Teil, den die meisten Teams nicht bedacht haben.

Wenn ein Mensch eine Dokumentationsseite liest, kann er sich ein Urteil bilden. Ihm könnte auffallen, dass die Screenshots alt aussehen oder dass ein Kommentar am Ende der Seite besagt, dass der Prozess geändert wurde. Er kann darauf blinzeln und denken: "Das scheint veraltet zu sein".

Ein KI-Assistent kann das alles nicht tun. Er liest den Text, verarbeitet ihn als Tatsache und gibt mit vollem Vertrauen eine Antwort. Wenn in der Dokumentation ein veralteter Endpunkt beschrieben wird, wird die KI fröhlich empfehlen, ihn zu integrieren. Wenn in der Dokumentation auf eine Infrastruktur verwiesen wird, die vor sechs Monaten ersetzt wurde, wird die KI die alte Konfiguration als aktuell beschreiben. Ohne zu zögern.

Und das macht die Sache noch schlimmer, als sie klingt: 66% der Entwickler sagen bereits, dass das größte Problem mit KI-Tools darin besteht, dass sie Ergebnisse liefern, die "fast richtig, aber nicht ganz richtig" sind. Eine veraltete Dokumentation trägt direkt zu diesem Problem bei. Die KI halluziniert nicht. Sie gibt veraltete Inhalte originalgetreu wieder, und es gibt keine Möglichkeit für den Erbauer, den Unterschied zu erkennen.

Der Bauherr verlässt sich auf die KI. Die KI verlässt sich auf die Dokumentation. Wenn die Dokumentation veraltet ist, liefert diese Vertrauenskette mit Sicherheit eine falsche Antwort.

Das war natürlich schon immer ein Problem. Veraltete Inhalte haben die Menschen schon immer verwirrt. Aber der Schaden wurde eingedämmt, weil menschliche Leser es manchmal erkennen konnten. KI-Vermittler können das nicht. Sie verstärken veraltete Inhalte, indem sie sie in großem Umfang und mit Autorität an Menschen weitergeben, die keinen Grund haben, sie anzuzweifeln.

Frische ist nicht mehr nur eine Frage der Qualität der Inhalte. Es ist eine Frage der Zuverlässigkeit für jeden KI-gesteuerten Workflow, der deine Dokumente berührt.

Das Wort "Entwickler" ist zu eng gefasst

Die Menschen, die im Jahr 2026 Software entwickeln, bezeichnen sich nicht alle als Entwickler. Manche sind Designer, die Claude auffordern, einen funktionierenden Prototyp zu bauen. Einige sind Produktmanager, die Cursor benutzen, um interne Tools zu entwickeln. Andere sind Datenanalysten, die eine Datenpipeline in natürlicher Sprache beschreiben und sie von einem Agenten zusammenstellen lassen. Beim Start Summit hatte die Hälfte der Hackathon-Teams Mitglieder, die keinerlei Programmierkenntnisse hatten und am Ende des Wochenendes eine funktionierende Software lieferten.

Ramp ist ein gutes Beispiel. Das Finanzunternehmen stieg von einer Bewertung von 5,8 Mrd. USD im Jahr 2023 auf 32 Mrd. USD Ende 2025 und überschritt dabei einen Jahresumsatz von 1 Mrd. USD. Es ist eines der am schnellsten wachsenden Startups der Geschichte. Ein viel diskutierter Teil ihres Ansatzes: Produktmanager bauen Funktionen direkt mit KI-Tools, anstatt in einem Engineering Backlog zu warten. PMs bei Ramp schreiben nicht nur Spezifikationen. Sie liefern den Code. Die KI kümmert sich um die Implementierung. Der PM kümmert sich um die Absicht.

Das ist keine Abkürzung. Ein neues Betriebsmodell, das in einem Umfang funktioniert, der es wirklich schwer macht, es als Experiment abzutun.

Die interne Studie von Anthropic ist hier aufschlussreich. Bei einer Befragung von 132 Ingenieuren (https://fortune.com/2025/12/02/how-anthropics-safety-first-approach-won-over-big-business-and-how-its-own-engineers-are-using-its-claude-ai/) über die Nutzung von Claude gaben die Ingenieure an, dass sie Claude für etwa 60 % ihrer Arbeitsaufgaben nutzen. Die häufigsten Anwendungen? Das Debuggen von bestehendem Code, das Verstehen, was Teile der Codebasis tun, und die Implementierung neuer Funktionen. Die Ingenieure gaben an, dass sie Claude eher mit Aufgaben betrauen, die "nicht komplex sind, sich wiederholen und bei denen die Codequalität nicht entscheidend ist". Und 27 % der Arbeit, die sie jetzt mit Claude erledigen, hätten sie vorher gar nicht gemacht.

Das ist das eigene Team von Anthropic. Die Leute, die das Modell entwickelt haben, nutzen es als Dokumentationsleser, als Codebase-Navigator und als Generator für erste Entwürfe. Alle anderen machen das Gleiche, nur mit ihren Dokumenten statt mit ihren.

Anthropic hat diese Persona bewusst als "Builder" bezeichnet. Ihre Werkzeuge sind nicht nur für professionelle Softwareentwickler gedacht, sondern für jeden, der beschreiben kann, was er bauen will. Wenn Claude mit MCP aus einem Figma-Entwurf eine vollständige Anwendung erstellen kann, löst sich die traditionelle Grenze zwischen "Entwickler" und "Nicht-Entwickler" auf.

Das hat echte Auswirkungen auf jeden, der Dokumentationen pflegt oder sich um die Erfahrung von Entwicklern kümmert. Deine Zielgruppe ist nicht mehr auf Menschen beschränkt, die wissen, was ein REST-Endpunkt ist. Sie umfasst jeden, dessen KI-Assistent mit deinem Produkt interagieren könnte. Der PM bei Ramp, der eine Funktion mit deiner API ausliefert? Wahrscheinlich liest er deine Dokumentation nie direkt. Ihr KI-Agent wird es aber auf jeden Fall tun.

Was das für die Dokumentation bedeutet

Wenn die Dokumentation jetzt zwei Zielgruppen bedient, nämlich menschliche Leser und KI-Vermittler, muss sie für beide funktionieren. Das klingt offensichtlich. In der Praxis macht das aber fast niemand.

Hier ist, was meiner Meinung nach wirklich wichtig ist:

**Maschinenlesbare Formate neben menschenlesbaren Formaten ** Wenn deine API-Dokumente eine schön gerenderte HTML-Seite sind, die ein LLM auslesen und parsen muss, arbeitet die KI härter als sie sollte. Biete die unbearbeitete OpenAPI-Spezifikation zusammen mit der gerenderten Version an. Liefern Sie saubere Markdowns. Mach die Spezifikationen zugänglich, ohne dass die KI das Seitenlayout interpretieren muss.

**Struktur auf Blockebene statt Erzählung auf Seitenebene ** KI-Assistenten konsumieren die Dokumentation nicht Seite für Seite. Sie extrahieren relevante Abschnitte. Ein Dokument mit klaren Überschriften, in sich abgeschlossenen Absätzen und expliziter Semantik auf Blockebene ist für eine KI wesentlich nützlicher als eine fließende Erzählung, bei der man die ganze Seite lesen muss, um den Kontext zu verstehen.

Vertrauere auf Signale, dass Maschinen lesen können. Wann wurde dieses Dokument zuletzt überprüft? Ist es noch aktuell? Wurde der Inhalt mit einer Kennzeichnung versehen? Diese Signale müssen in einer Form vorliegen, auf die die KI zugreifen kann, nicht nur als visuelle Hinweise auf einer Webseite. Ein Freshness Score, ein Verfallsstatus, ein Überprüfungsdatum - das sind die Metadaten, anhand derer eine KI entscheiden kann, ob ein Dokument als Quelle sicher ist.

Frische als Voraussetzung, nicht als Merkmal. Wenn ein KI-Assistent einem Builder eine sichere Antwort auf der Grundlage eines veralteten Endpunkts gibt, ist der Schaden schlimmer als eine 404. Der Builder baut darauf auf. Liefert sie aus. Dann geht sie in der Produktion kaputt, und niemand weiß, warum, bis jemand die Ursache auf die Dokumentation zurückführt, die schon vor Monaten hätte aktualisiert werden müssen. Jedes Dokument, auf das sich eine KI beziehen könnte, braucht einen Mechanismus, um zu beweisen, dass es noch aktuell ist. (Das ist genau das Problem, das wir mit Rasepi lösen wollen, um ganz offen zu sein. Erzwungenes Verfallsdatum für Dokumentationsblöcke, damit sich veraltete Inhalte nicht verstecken können.)

Erste Schritte: Überprüfe deine aktuellen Dokumentationen

Wenn du bis hierher gelesen hast und denkst: "Okay, aber was mache ich eigentlich am Montag?", hier sind vier konkrete Dinge, die du diese Woche überprüfen kannst.

1. Teste deine Dokumente durch eine KI. Öffne Claude oder ChatGPT und bitte sie, dein Produkt in ein realistisches Szenario zu integrieren. Nutze nicht dein internes Wissen. Schau dir einfach an, was die KI produziert. Ist es korrekt? Ist es aktuell? Verwendet sie die richtigen Endpunkte, die richtige SDK-Version, den richtigen Authentifizierungsfluss? Wenn die KI etwas falsch macht, ist es das, was die Bauherren jetzt bekommen.

2. Überprüfe, ob die Inhalte veraltet sind. Nimm deine fünf meistbesuchten Dokumentationsseiten und frage: Wann wurde diese Seite zuletzt überarbeitet? Beschreiben sie immer noch den aktuellen Stand des Produkts? Wenn du diese Frage nicht sicher beantworten kannst, kann das auch eine KI nicht. Das ist die wichtigste Maßnahme für die meisten Teams.

**3. Liefern Sie maschinenlesbare Formate ** Wenn Sie keine /llms.txt-Datei haben, erstellen Sie eine. Wenn deine API-Referenz nur als gerendertes HTML vorliegt, exportiere die OpenAPI-Rohdaten und mache sie zugänglich. Wenn deine Dokumente in einem CMS sind, das keine sauberen Markdown-Dateien ausgibt, ist das ein Problem, das du jetzt lösen solltest.

4. Füge Überprüfungsdaten und Freshness-Metadaten hinzu. Selbst etwas Einfaches wie ein last-reviewed-Feld in deinem Content Management System, ein obligatorischer Überprüfungszyklus für stark frequentierte Seiten. Das gibt sowohl den Menschen als auch der KI ein Signal, ob die Inhalte vertrauenswürdig sind. Tools wie Rasepi können dies mit einem erzwungenen Ablauf auf Blockebene automatisieren, aber auch ein manueller Prozess ist besser als nichts.

Der stille Wandel in der Darstellung von Produkten

Es gibt noch eine weitere Konsequenz, die es wert ist, direkt angesprochen zu werden.

Deine Dokumentation ist nicht mehr nur ein Referenzhandbuch für Entwickler. Sie ist das Ausgangsmaterial, das KI-Assistenten nutzen, um dein Produkt in der Welt zu repräsentieren. Wenn ein Entwickler Claude fragt, wie er dein Produkt nutzen kann, wird Claudes Antwort von dem geprägt, was er in deinen Unterlagen finden und analysieren kann.

Gute Dokumente, gute Antwort. Veraltet, mehrdeutig, in HTML eingeschlossen, das für ein Modell schwer zu analysieren ist? Schlechte Antwort oder eine falsche Antwort. So einfach ist das.

Die Qualität der KI-Antwort zu deinem Produkt ist jetzt ein direkter Indikator für die Erfahrung deiner Entwickler. Die meisten Unternehmen behandeln das noch nicht so.

Stripe, Vercel, Cloudflare und Anthropic sind die Vorreiter in diesem Bereich und behandeln die Lesbarkeit der KI als ein erstklassiges Anliegen. Eine grundlegende Anforderung, die bestimmt, wie die Dokumentation geschrieben, strukturiert und gepflegt wird. Das ist kein Thema für das nächste Quartal.

Der Entwickler, der gerade in Claude sitzt, beschreibt, was er bauen will, und erwartet, dass der Code innerhalb von Minuten funktioniert. Er wird vielleicht nie wieder eine Dokumentationsseite besuchen. Aber die KI, die sie bedient, wird es tun. Ständig.

Diese KI ist jetzt dein häufigster Leser. Die Frage ist nur, ob deine Dokumente darauf vorbereitet sind.

Die beste Strategie für das Entwicklererlebnis im Jahr 2026 ist kein Konferenzvortrag oder eine Schnellstartanleitung. Sie muss sicherstellen, dass die KI es richtig macht.

*Dieser Beitrag bezieht sich auf öffentlich zugängliche Forschungsergebnisse und Produktdokumentationen. Die Statistiken stammen aus GitHub's 2024 developer survey, der Stack Overflow 2024 Developer Survey, Index.dev's 2026 developer productivity report, Incremys Claude statistics und Fortune's reporting on Anthropic. Die /llms.txt-Spezifikation wird auf llmstxt.org gepflegt. Das Model Context Protocol ist unter modelcontextprotocol.io dokumentiert.

Wie Rasepi-Übersetzungen tatsächlich funktionieren und warum sie wie dein Team klingen

2026-03-31T00:00:00Z

Wenn du schon einmal ein Dokument durch Google Translate oder ein anderes Übersetzungsprogramm laufen lassen hast, kennst du das Ergebnis. Technisch korrekt. Tonal falsch. Dein Produkt wird plötzlich anders genannt. Die interne Kurzschrift deines Teams verschwindet. Das formelle "Du", wo dein Unternehmen das informelle "Sie" verwendet, oder umgekehrt.

Das Ergebnis wird übersetzt, aber es klingt nicht nach dir.

Dafür habe ich das Übersetzungssystem von Rasepi entwickelt. Es geht nicht darum, ob wir die Dokumentation übersetzen können (das kann inzwischen jedes Tool), sondern darum, ob wir sie so übersetzen können, dass sie tatsächlich so klingt, als hätte unser Team sie geschrieben.

Die Antwort ist ja. Und es braucht kein Team von professionellen Übersetzern, um das zu erreichen.

Übersetzungen, die wie dein Team klingen](/de/blog/img/natural-translations.svg)

Nur was sich geändert hat, wird übersetzt

Die meisten Dokumentationsplattformen übersetzen ganze Seiten. Wenn du einen Satz änderst, wird das ganze Dokument neu übersetzt. Jede Sprache, jeder Absatz, egal ob er geändert wurde oder nicht.

Rasepi funktioniert anders. Es verfolgt jeden Absatz einzeln. Wenn du einen Abschnitt eines Dokuments mit 20 Abschnitten bearbeitest, wird nur dieser eine Abschnitt neu übersetzt. Die anderen 19, in allen Sprachen, bleiben genau so, wie sie waren.

Das bedeutet zwei Dinge:

Deine Übersetzungskosten sinken drastisch. Wir reden hier von 94% weniger für typische Änderungen. Die meisten Aktualisierungen betreffen einen oder zwei Abschnitte, nicht die ganze Seite.
Übersetzungen, die du bereits überprüft hast, bleiben stabil. Wenn dein deutsches Team letzte Woche eine Übersetzung genehmigt hat, hat die Bearbeitung eines nicht verwandten Absatzes im Englischen keinen Einfluss auf den genehmigten Text.

Das System weiß, was sich geändert hat, denn jeder Absatz hat eine eindeutige Identität und einen inhaltlichen Fingerabdruck. Wenn sich der Fingerabdruck ändert, wird dieser spezielle Absatz zur Neuübersetzung markiert. Sonst nichts.

Dein Glossar, deine Terminologie

Hier wird es interessant.

Jedes Unternehmen hat sein eigenes Vokabular. "Sprint Review" könnte in deinen deutschen Dokumenten "Sprint Review" bleiben, weil dein Berliner Team den englischen Begriff verwendet. Oder es wird zu "Sprint-Überprüfung", weil dein Münchner Team die deutsche Version bevorzugt. "Knowledge Base" könnte "Wissensdatenbank" oder "Knowledge Base" heißen oder etwas ganz anderes, das dein Team intern geprägt hat.

Mit Rasepi kannst du für jede Sprache ein Glossar erstellen. Dabei handelt es sich um eine Liste von Begriffen und ihren genehmigten Übersetzungen. Wenn ein Absatz übersetzt wird, prüft das System zuerst dein Glossar. Jeder Begriff in deiner Liste wird genau so übersetzt, wie du ihn definiert hast. Jedes Mal. In jedem Dokument.

Du kannst dein Glossar direkt in Rasepi verwalten:

Füge einen Begriff nach dem anderen hinzu, wenn du Unstimmigkeiten bemerkst
Importiere eine CSV, wenn du bereits eine Terminologieliste aus einem anderen System hast
Exportiere dein Glossar, um es mit externen Übersetzern oder anderen Tools zu teilen

Das Glossar funktioniert pro Sprachpaar. Dein Englisch-Deutsch-Glossar ist von deinem Englisch-Französisch-Glossar getrennt. Das ist wichtig, weil ein und derselbe englische Begriff in den verschiedenen Sprachen unterschiedlich behandelt werden kann. "Sprint Review" könnte auf Deutsch Englisch bleiben, aber auf Japanisch übersetzt werden.

Wenn du dein Glossar aktualisierst, tritt die Änderung in Kraft, wenn ein Absatz das nächste Mal in diese Sprache übersetzt wird. Du musst nicht alles von Hand neu übersetzen. Der nächste natürliche Bearbeitungszyklus übernimmt die Änderung.

Stilregeln: Damit die Übersetzungen so klingen, als hättest du sie geschrieben

Glossare behandeln einzelne Wörter. Aber eine Übersetzung kann alle richtigen Begriffe verwenden und trotzdem falsch klingen. Falscher Ton. Datumsangaben im falschen Format. Zahlen mit dem falschen Trennzeichen. Währungssymbole an der falschen Stelle.

Dafür sind die Stilregeln da.

Für jede Sprache kannst du eine Sammlung von Regeln einrichten, die bestimmen, wie die Übersetzungen gestaltet werden:

Formatierungskonventionen

Das sind die Details, die dafür sorgen, dass sich ein Dokument wie ein Original anfühlt und nicht wie "offensichtlich aus dem Englischen übersetzt":

Datums- und Zeitformate. 24-Stunden-Uhr für Deutsch, AM/PM für Englisch, und mehr
Zahlenformatierung. Komma als Dezimaltrennzeichen im Deutschen (3,14 statt 3.14), Punkt für Tausender
Interpunktionsregeln.** Akademische Abschlussformate, Anführungszeichen und andere regionale Konventionen

Du wählst die Konventionen aus, die den Standards deines Unternehmens entsprechen. Rasepi wendet sie auf jede Übersetzung in dieser Sprache an, und zwar für jedes Dokument.

Benutzerdefinierte Anweisungen

Hier werden die Dinge wirklich mächtig. Benutzerdefinierte Anweisungen sind einfachsprachliche Direktiven, die der Übersetzungsmaschine sagen, wie sie mit deinen Inhalten umgehen soll. Du schreibst sie in normalen Sätzen, und die Maschine folgt ihnen.

Einige Beispiele:

"Verwende einen freundlichen, diplomatischen Ton " für ein Unternehmen, das eine ansprechende Dokumentation wünscht
"Verwende immer die förmliche Form 'Sie', niemals 'du'" für professionelle deutsche Kommunikation
"Verwende die britische Schreibweise: Farbe, Organisation, Lizenz ", wenn dein englischsprachiges Publikum aus dem Vereinigten Königreich kommt.
"Setze Währungssymbole nach dem numerischen Betrag ", um den europäischen Konventionen zu entsprechen.
"Verwende bei der Beschreibung von API-Endpunkten den Imperativ " für technische Dokumente, die direkt wirken sollen

Du kannst bis zu 200 eigene Anweisungen pro Sprache hinzufügen. Sie funktionieren neben deinem Glossar und deinen Formatierungsregeln, und die Übersetzungsmaschine berücksichtigt sie bei jeder Übersetzung.

Formalität

Im Deutschen gibt es "du" und "Sie". Im Französischen gibt es "tu" und "vous". Im Japanischen gibt es mehrere Ebenen der Höflichkeit. Selbst in Sprachen, in denen es keine offensichtlichen formellen/informellen Pronomen gibt, gibt es tonale Unterschiede, die wichtig sind.

Mit Rasepi kannst du für jede Sprache die Formalitätsstufe festlegen. Einmal eingestellt, wird jeder übersetzte Absatz in diesem Tonfall wiedergegeben. Wenn dein Unternehmen seine Leser auf Französisch förmlich anspricht ("vous"), auf Deutsch aber informell ("du"), wird jede Übersetzung genau das tun.

Es funktioniert alles zusammen

Das ist das Wichtigste: Glossarbegriffe, Formatierungskonventionen, benutzerdefinierte Anweisungen und Formalitätseinstellungen gelten für jede Übersetzung zur gleichen Zeit. Du wählst nicht das eine oder das andere aus. Du legst sie alle einmal fest, und jeder Absatz, der übersetzt wird, unterliegt denselben Regeln.

Das Ergebnis sind Übersetzungen, die sich so lesen, als hätte sie jemand aus deinem Team vor Ort geschrieben. Nicht wie eine Maschine, die jeden Satz übersetzt hat, ohne etwas über dein Unternehmen zu wissen.

Jede Sprache kann ihren eigenen Inhalt haben

Das ist die Funktion, die die Leute am meisten überrascht.

In Rasepi ist ein übersetztes Dokument keine geschlossene Kopie des Originals. Jede Sprachversion kann Inhalte haben, die es nur in dieser Sprache gibt.

Warum ist das wichtig?

Weil unterschiedliche Märkte unterschiedliche Dinge brauchen:

Deine deutsche Dokumentation braucht vielleicht einen Abschnitt über die Einhaltung der DSGVO (GDPR), der für die US-Version nicht gilt.
Dein japanisches Team braucht vielleicht einen Hinweis auf lokale Werkzeuge, die sonst niemand benutzt
Dein brasilianisches Büro braucht vielleicht einen Hinweis auf regionale Steuervorschriften

Bei den meisten Übersetzungstools bedeutet das Hinzufügen von Inhalten zu einer Sprachversion, dass sie überschrieben werden, wenn jemand das nächste Mal aus dem Englischen neu übersetzt. Die Teams finden das schnell heraus und fügen keine lokalen Inhalte mehr hinzu. Sie erstellen Schattendokumente in Notion oder Slack oder anderswo, und schon hast du zwei Systeme, denen niemand so recht traut.

In Rasepi werden einzigartige Inhalte als zu dieser Sprache gehörig gekennzeichnet. Er wird nie durch eine Neuübersetzung überschrieben. Er wird nicht gelöscht, wenn sich die englische Quelle ändert. Er lebt neben dem übersetzten Inhalt als natürlicher Teil des Dokuments.

Das Gleiche gilt für die Struktur. Wenn deine japanischen Übersetzer nummerierte Listen bevorzugen, während die englische Version Aufzählungszeichen verwendet (eine gängige Konvention in japanischen technischen Texten), können sie das Format ändern. Rasepi behält diese Wahl bei zukünftigen Aktualisierungen bei.

Jede Sprachversion ist ein erstklassiges Dokument, keine Nur-Lese-Spiegelung.

Automatisch und menschlich: Sie arbeiten zusammen

Rasepi zwingt dich nicht dazu, dich zwischen maschineller und menschlicher Übersetzung zu entscheiden. Es unterstützt beides, und es kennt den Unterschied.

Wenn ein Absatz maschinell übersetzt wird und sich der Quelltext ändert, übersetzt Rasepi ihn automatisch neu. Ein menschliches Eingreifen ist nicht nötig. Das Glossar und die Stilregeln sorgen dafür, dass alles einheitlich bleibt.

Wenn ein Absatz von einem menschlichen Übersetzer manuell bearbeitet wurde, z. B. um kulturelle Nuancen zu berücksichtigen oder einen Kontext hinzuzufügen, den eine Maschine nicht erkennen würde, respektiert Rasepi diese Arbeit. Wenn sich der Quelltext ändert, kennzeichnet das System den Absatz als überarbeitungsbedürftig, überschreibt aber niemals stillschweigend menschliche Bearbeitungen. Der Übersetzer sieht, was sich im Quelltext geändert hat und entscheidet, wie er seine Version aktualisieren möchte.

Das bedeutet, dass sich die Qualität deiner Übersetzung mit der Zeit verbessert. Die maschinelle Übersetzung übernimmt den größten Teil. Menschliche Übersetzer/innen konzentrieren sich auf die Abschnitte, die eine menschliche Note brauchen. Keiner von beiden tritt auf die Arbeit des anderen.

Zwei Modi: immer aktuell oder auf Anfrage übersetzen

Für jede Sprache wählst du, wann die Übersetzungen stattfinden:

Immer übersetzen. Jedes Mal, wenn jemand das Ausgangsdokument speichert, werden geänderte Absätze sofort neu übersetzt. Am besten für deine wichtigsten Sprachen, bei denen die Leser/innen minutengenaue Übersetzungen erwarten.
Bei der Anzeige übersetzen. Geänderte Absätze werden markiert, aber erst übersetzt, wenn jemand das Dokument in der betreffenden Sprache öffnet. Ideal für Sprachen, die weniger häufig verwendet werden. Keine verschwendeten Übersetzungskosten für Inhalte, die niemand liest.

Beide Modi verwenden das gleiche Glossar, die gleichen Stilregeln und die gleiche Qualität. Der einzige Unterschied ist das Timing.

So sieht das in der Praxis aus

Angenommen, du leitest ein Unternehmen mit Teams in London, München, Paris und Tokio. Deine Dokumentation ist in Englisch verfasst.

Ein Produktmanager in London aktualisiert den Deployment Guide. Ein Abschnitt über einen neuen CI/CD-Schritt.

Das passiert folgendermaßen:

Deutsch (immer übersetzen). Der geänderte Abschnitt wird innerhalb von Sekunden neu übersetzt. Aus "Sprint Review" wird "Sprint-Überprüfung", weil das in deinem Glossar steht. Formelles "Sie", weil das deine Formalitätseinstellung ist. Datumsangaben im 24-Stunden-Format, weil das die von dir eingestellte Regel ist. Die benutzerdefinierte Anweisung "Verwende einen direkten, gebieterischen Ton" prägt die Formulierung. Der DSGVO-Abschnitt, den das Münchner Team hinzugefügt hat? Unangetastet.
Französisch (immer übersetzen). Derselbe Abschnitt, sofort neu übersetzt. "Vous" Förmlichkeit. Französische Glossarbegriffe angewendet. Währungssymbole nach den Zahlen gemäß deiner Anweisung. Der Rest des Dokuments bleibt genau so, wie das Pariser Büro es zuletzt überprüft hat.
Japanisch (beim Anzeigen übersetzen). Der geänderte Abschnitt wird als veraltet gekennzeichnet. Wenn jemand in Tokio das Dokument öffnet, wird es sofort übersetzt. Die benutzerdefinierte Formatierung der nummerierten Liste bleibt erhalten. Ihre lokale Tooling-Notiz wird beibehalten.

Eine Bearbeitung. Drei Sprachen aktualisiert. Keine Neuübersetzung des gesamten Dokuments. Einheitliche Terminologie, einheitlicher Ton und Respekt für die lokalen Ergänzungen jedes Teams.

Apropos Sprachqualität

Die Übersetzungsmaschine, die hinter all dem steht, ist DeepL, dieselbe Technologie, die auch die Funktion Talk to Docs von Rasepi unterstützt. Du kannst mit deiner Dokumentation sprechen und bekommst die Antworten laut vorgelesen. DeepL Voice kümmert sich um die gesprochene Interaktion. Das bedeutet, dass dieselbe Terminologiekonsistenz, dieselben Stilregeln und dieselbe Sprachqualität wie bei den schriftlichen Übersetzungen auch für die Sprachunterhaltungen gelten. Deine Glossarbegriffe und benutzerdefinierten Anweisungen klingen richtig, egal ob dein Team liest oder zuhört.

Übersetzungen, die wie dein Team klingen, sind kein Luxus. Für Unternehmen, die in mehreren Sprachen arbeiten, sind sie der Unterschied zwischen einer Dokumentation, der man vertraut, und einer, um die man herumarbeitet. Glossare, Stilregeln, benutzerdefinierte Anweisungen, intelligente Neuübersetzung und einzigartige Inhalte für jede Sprache machen das möglich. Automatisch, vom ersten Tag an.

Deine Dokumentation sollte in jeder Sprache wie dein Team klingen. Nicht wie eine Maschine. Nicht wie ein anderes Unternehmen. Wie du.

Mehrsprachiges Publizieren in Aktion sehen →

Im Inneren der Translation Engine: Glossare, Stilregeln und intelligente Rückübersetzung

2026-03-31T00:00:00Z

Unser vorheriger Architektur-Beitrag behandelte Plugins, Action Guards und das Pipeline-System. In diesem Beitrag gehen wir näher auf die Übersetzungs-Engine ein, die Rasepi meiner Meinung nach grundlegend von allen anderen Dokumentationsplattformen unterscheidet.

Es geht nicht um das Marketing, dass Absätze statt Seiten übersetzt werden. Der eigentliche Code. Wie Glossare pro Tenant aufgelöst werden, wie die Stilregeln und benutzerdefinierten Anweisungen von DeepL jede Übersetzung beeinflussen, wie Content Hashing die Erkennung von veralteten Inhalten steuert und wie der Orchestrator entscheidet, welche Blöcke neu übersetzt werden.

Die Übersetzungspipeline

Wenn ein Benutzer ein Dokument speichert, übersetzt das System nicht einfach alles neu. Es führt eine ganz bestimmte Sequenz durch:

Es zerlegt das TipTap JSON in einzelne Blöcke
Inhalts-Hashes vergleichen, um festzustellen, welche Blöcke sich tatsächlich geändert haben
Löse für geänderte Blöcke das Glossar und die Stilregel-Liste des Tenants für das Sprachpaar auf
Wende Stilregeln, benutzerdefinierte Anweisungen und Formalitäten aus der Tenant-Konfiguration an
Sende nur geänderte Blöcke an DeepL
Übersetzungsblöcke aktualisieren und Inhaltshashes synchronisieren

Jeder Schritt ist ein eigener Dienst mit einer eigenen Schnittstelle. Das ist wichtig, weil jeder Schritt gegen einen anderen ausgetauscht werden kann: einen anderen Übersetzungsanbieter, einen anderen Hash-Algorithmus oder eine andere Glossarquelle.

Glossarauflösung: mieterübergreifend, DeepL-synchronisiert

DeepL Glossare haben eine Einschränkung, von der die meisten Menschen nichts wissen: **Sie sind unveränderlich. ** Du kannst ein DeepL Glossar nicht bearbeiten. Jede Änderung bedeutet, dass das alte Glossar gelöscht und ein neues erstellt wird.

Rasepi behandelt dies, indem es die Datenbank als Quelle der Wahrheit und DeepL Glossare als Wegwerf-Artefakte zur Laufzeit behandelt. Die Entität TenantGlossary speichert alles lokal:

public class TenantGlossary : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string SourceLanguage { get; set; }     // e.g. "en"
    public string TargetLanguage { get; set; }     // e.g. "de"
    public string? DeepLGlossaryId { get; set; }   // Runtime DeepL ID
    public DateTime? LastSyncedAt { get; set; }
    public bool IsDirty { get; set; } = true;      // Triggers re-sync
    public ICollection<TenantGlossaryEntry> Entries { get; set; }
}

Wenn ein Benutzer einen Glossareintrag hinzufügt, z.B. die Zuordnung von "Sprint Review" zu "Sprint-Überprüfung" für EN→DE, wird der Datenbankeintrag sofort aktualisiert und IsDirty wird auf true gesetzt. Das Glossar DeepL wird nicht sofort neu erstellt. Es wird erst nach und nach neu erstellt, wenn es das nächste Mal für eine Übersetzung benötigt wird.

Der Sync-Fluss

Vor jedem Übersetzungsaufruf löst das System das Glossar auf:

public async Task<string?> GetOrSyncDeepLGlossaryIdAsync(
    string sourceLanguage, string targetLanguage,
    CancellationToken ct = default)
{
    var glossary = await _db.TenantGlossaries
        .Include(g => g.Entries)
        .FirstOrDefaultAsync(g =>
            g.SourceLanguage == sourceLanguage &&
            g.TargetLanguage == targetLanguage, ct);

    if (glossary is null || glossary.Entries.Count == 0)
        return null;

    if (!glossary.IsDirty && glossary.DeepLGlossaryId is not null)
        return glossary.DeepLGlossaryId;

    // Dirty - delete old, create new
    if (glossary.DeepLGlossaryId is not null)
        await _deepL.DeleteGlossaryAsync(glossary.DeepLGlossaryId);

    var entries = glossary.Entries
        .ToDictionary(e => e.SourceTerm, e => e.TargetTerm);

    var deepLGlossary = await _deepL.CreateGlossaryAsync(
        $"rasepi-{glossary.Id}",
        glossary.SourceLanguage,
        glossary.TargetLanguage,
        entries);

    glossary.DeepLGlossaryId = deepLGlossary.GlossaryId;
    glossary.IsDirty = false;
    glossary.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return glossary.DeepLGlossaryId;
}

Drei Dinge sind hier erwähnenswert:

Lazy sync. Wir rufen die DeepL API nur auf, wenn tatsächlich eine Übersetzung benötigt wird. Die Bearbeitung von Glossareinträgen löst nicht Dutzende von API-Aufrufen aus.
Mieterisolierung. Die Abfrage durchläuft die globalen EF-Abfragefilter, sodass TenantGlossaries automatisch gescannt wird. Die Glossareinträge von Tenant A gelangen nicht in die Übersetzungen von Tenant B.
Ein Glossar pro Sprachenpaar. DeepL erzwingt dies ohnehin. Ein EN→DE-Glossar, ein EN→FR-Glossar, und so weiter. Das (SourceLanguage, TargetLanguage)-Paar ist pro Tenant eindeutig.

Glossar-Einträge

Einzelne Einträge sind nur Begriffszuordnungen:

public class TenantGlossaryEntry
{
    public Guid Id { get; set; }
    public Guid GlossaryId { get; set; }
    public string SourceTerm { get; set; }   // e.g. "Sprint Review"
    public string TargetTerm { get; set; }   // e.g. "Sprint-Überprüfung"
}

Die API bietet dir vollständiges CRUD sowie CSV-Import/Export für die Massenverwaltung:

POST   /api/admin/glossaries                       Create glossary
POST   /api/admin/glossaries/{id}/entries           Add term
PUT    /api/admin/glossaries/{id}/entries/{entryId}  Update term
DELETE /api/admin/glossaries/{id}/entries/{entryId}  Remove term
POST   /api/admin/glossaries/{id}/import            Import CSV
GET    /api/admin/glossaries/{id}/export            Export CSV
POST   /api/admin/glossaries/{id}/sync              Force DeepL sync

Der CSV-Import ist besonders nützlich für Teams, die von bestehenden Translation-Memory-Systemen migrieren. Exportiere deine Begriffe, bereinige sie, importiere sie in Rasepi, und der nächste Übersetzungslauf verwendet das neue Glossar automatisch.

Stilregeln, benutzerdefinierte Anweisungen und Formalitäten

Glossare kümmern sich um die Terminologie. Aber Terminologie ist nur die halbe Miete. Eine Übersetzung kann alle richtigen Wörter verwenden und trotzdem falsch klingen. Falscher Ton, falsches Datumsformat, falsche Zeichensetzungskonventionen.

Die Style Rules API (v3) von DeepL schafft hier Abhilfe. Du kannst wiederverwendbare Stilregel-Listen erstellen, die zwei Arten von Steuerelementen kombinieren:

Konfigurierte Regeln, vordefinierte Formatierungskonventionen für Datumsangaben, Zeitangaben, Interpunktion, Zahlen und mehr
Benutzerdefinierte Anweisungen, Freitextanweisungen, die den Ton, die Formulierung und bereichsspezifische Konventionen bestimmen

Rasepi erstellt und verwaltet diese pro Tenant und pro Zielsprache. Die Entität TenantStyleRuleList speichert die DeepL style_id neben den konfigurierten Regeln und benutzerdefinierten Anweisungen des Tenants:

public class TenantStyleRuleList : ITenantScoped
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public string Name { get; set; }
    public string TargetLanguage { get; set; }      // e.g. "de"
    public string? DeepLStyleId { get; set; }       // Runtime DeepL style_id
    public string ConfiguredRulesJson { get; set; }  // Serialized configured rules
    public bool IsDirty { get; set; } = true;
    public DateTime? LastSyncedAt { get; set; }
    public ICollection<TenantCustomInstruction> CustomInstructions { get; set; }
}

Erstellen von Stilregel-Listen

Wenn ein Admin Übersetzungsregeln für Deutsch einrichtet, ruft Rasepi die v3 API von DeepL auf, um die Stilregel-Liste zu erstellen. So sieht das aus:

public async Task<string> CreateOrSyncStyleRuleListAsync(
    TenantStyleRuleList ruleList, CancellationToken ct = default)
{
    if (!ruleList.IsDirty && ruleList.DeepLStyleId is not null)
        return ruleList.DeepLStyleId;

    // DeepL style rule lists are mutable - we can update in place
    if (ruleList.DeepLStyleId is not null)
    {
        // Replace configured rules on existing list
        await _httpClient.PutAsJsonAsync(
            $"v3/style_rules/{ruleList.DeepLStyleId}/configured_rules",
            JsonSerializer.Deserialize<JsonElement>(ruleList.ConfiguredRulesJson),
            ct);

        // Sync custom instructions
        await SyncCustomInstructionsAsync(ruleList, ct);

        ruleList.IsDirty = false;
        ruleList.LastSyncedAt = DateTime.UtcNow;
        return ruleList.DeepLStyleId;
    }

    // Create new style rule list
    var payload = new
    {
        name = $"rasepi-{ruleList.TenantId}-{ruleList.TargetLanguage}",
        language = ruleList.TargetLanguage,
        configured_rules = JsonSerializer.Deserialize<JsonElement>(
            ruleList.ConfiguredRulesJson),
        custom_instructions = ruleList.CustomInstructions.Select(ci => new
        {
            label = ci.Label,
            prompt = ci.Prompt,
            source_language = ci.SourceLanguage
        })
    };

    var response = await _httpClient.PostAsJsonAsync("v3/style_rules", payload, ct);
    var result = await response.Content.ReadFromJsonAsync<StyleRuleResponse>(ct);

    ruleList.DeepLStyleId = result.StyleId;
    ruleList.IsDirty = false;
    ruleList.LastSyncedAt = DateTime.UtcNow;
    await _db.SaveChangesAsync(ct);

    return ruleList.DeepLStyleId;
}

Anders als Glossare sind DeepL Stilregel-Listen veränderbar. Du kannst konfigurierte Regeln mit PUT /v3/style_rules/{style_id}/configured_rules ersetzen, und benutzerdefinierte Anweisungen können individuell hinzugefügt, aktualisiert oder gelöscht werden. Das ist viel besser für die iterative Verfeinerung geeignet.

Wie konfigurierte Regeln aussehen

Konfigurierte Regeln decken Formatierungskonventionen ab, die je nach Sprache oder Firmenpräferenz variieren. Dinge wie:

{
  "dates_and_times": {
    "time_format": "use_24_hour_clock",
    "calendar_era": "use_bc_and_ad"
  },
  "punctuation": {
    "periods_in_academic_degrees": "do_not_use"
  },
  "numbers": {
    "decimal_separator": "use_comma"
  }
}

Das hört sich trivial an, aber es wird schnell kompliziert. Ein deutsches Dokument, das das AM/PM-Zeitformat und durch Punkte getrennte Dezimalzahlen verwendet, liest sich für einen deutschen Leser einfach als "aus dem Englischen übersetzt". Wenn du use_24_hour_clock und use_comma für Dezimaltrennzeichen in allen deutschen Übersetzungen einstellst, wird das sofort behoben.

Benutzerdefinierte Anweisungen: Das ist die wahre Macht

Benutzerdefinierte Anweisungen sind Freitextanweisungen, bis zu 200 pro Stilregel-Liste, jede mit bis zu 300 Zeichen. Damit sagst du DeepL, wie die Übersetzung aussehen soll, und zwar in einfacher Sprache:

public class TenantCustomInstruction
{
    public Guid Id { get; set; }
    public Guid StyleRuleListId { get; set; }
    public string Label { get; set; }              // e.g. "Tone instruction"
    public string Prompt { get; set; }             // e.g. "Use a friendly, diplomatic tone"
    public string? SourceLanguage { get; set; }    // Optional source lang filter
}

Echte Beispiele von unseren Mietern:

"Use a friendly, diplomatic tone" für ein Startup, das ansprechende Dokumente braucht
"Always use 'Sie' form, never 'du'" für eine deutsche Anwaltskanzlei
"Translate 'deployment' as 'Bereitstellung', never 'Deployment'" für Begriffe, die eine kontextabhängige Handhabung benötigen, die über eine einfache Glossarzuordnung hinausgeht
"Use British English spelling (colour, organisation, licence)" für britische Unternehmen, die zwischen englischen Varianten übersetzen
"Put currency symbols after the numeric amount" zur Anpassung an europäische Konventionen

Benutzerdefinierte Anweisungen sind sehr hilfreich, wenn es um domänenspezifische Konventionen geht, die nicht in Glossareinträge passen. Ein Glossar ordnet einen Begriff einem anderen zu. In einer benutzerdefinierten Anweisung kann stehen: "Wenn du API-Dokumente übersetzst, verwende den Imperativ statt des Passivs. Das ist eine ganz andere Art der Kontrolle.

Formalität

DeepL's formality Parameter (default, more, less, prefer_more, prefer_less) ist immer noch als separates Steuerelement neben Stilregeln verfügbar. Deutsch "du" versus "Sie", Französisch "tu" versus "vous", japanische Höflichkeitsstufen. Diese werden pro Mietersprache über TenantLanguageConfig eingestellt:

public class TenantLanguageConfig : ITenantScoped
{
    public string LanguageCode { get; set; }
    public string DisplayName { get; set; }
    public bool IsEnabled { get; set; }
    public TranslationTrigger Trigger { get; set; }
    public string? Formality { get; set; }         // "more", "less", "prefer_more", etc.
    public string? StyleRuleListId { get; set; }   // Links to TenantStyleRuleList
    public string? TranslationProvider { get; set; }
    public int SortOrder { get; set; }
    public bool IsDefault { get; set; }
}

Formalitäten, Stilregeln und Glossare setzen sich zusammen. Ein einziger Übersetzungsaufruf kann alle drei enthalten:

var glossaryId = await GetOrSyncDeepLGlossaryIdAsync(sourceLang, targetLang, ct);
var styleId = await GetOrSyncStyleRuleListAsync(targetLang, ct);
var formality = tenantLanguageConfig.Formality ?? "default";

// Build the v2/translate request payload
var payload = new
{
    text = new[] { blockContent },
    source_lang = NormalizeLanguageCode(sourceLang),
    target_lang = NormalizeLanguageCode(targetLang),
    glossary_id = glossaryId,
    style_id = styleId,
    formality = formality,
    preserve_formatting = true,
    context = surroundingContext,  // Adjacent blocks, not billed
    model_type = "quality_optimized"
};

Zwei Dinge sind hier erwähnenswert:

Der context Parameter. Wir übergeben benachbarte Blöcke als Kontext, um die Übersetzungsqualität zu verbessern. DeepL nutzt dies, um Mehrdeutigkeiten aufzulösen, übersetzt oder berechnet sie aber nicht. Ein Absatz über "Zellen" wird anders übersetzt, wenn der umgebende Kontext ein Biologiedokument und eine Tabellenkalkulationsanleitung ist.
Modellauswahl. Jede Anfrage mit style_id oder custom_instructions verwendet automatisch das quality_optimized Modell von DeepL. Dies ist die höchste Qualitätsstufe. Du kannst sie nicht mit latency_optimized kombinieren, und das ist eine bewusste Einschränkung von DeepL. Für die Stilanpassung brauchst du das komplette Modell.

Warum das wichtiger ist, als du denkst

Stell dir vor, ein Unternehmen schreibt interne Dokumente auf Deutsch mit dem formlosen "du" und wechselt in einem übersetzten Abschnitt plötzlich zum formellen "Sie". Das sieht bestenfalls inkonsequent und schlimmstenfalls unprofessionell aus. Die Formalität regelt das. Aber die Formalität allein reicht nicht aus, um ein Dokument zu erkennen, das AM/PM-Zeitstempel verwendet, obwohl dein deutsches Büro das 24-Stunden-Format benutzt, oder das Währungssymbol vor die Zahl setzt, statt danach.

Alles zusammen (Stilregeln, benutzerdefinierte Anweisungen, Formalitäten, Glossare) ergibt Übersetzungen, die sich so lesen, als hätte sie jemand aus deinem Team geschrieben. Nicht wie die Ausgabe einer Maschine, die nicht weiß, dass dein Unternehmen existiert.

Die DeepL Service-Schicht

Die gesamte DeepL Kommunikation läuft über IDeepLService. Sie umhüllt das offizielle DeepL .NET SDK und verarbeitet v3 API-Aufrufe für Stilregeln:

public interface IDeepLService
{
    // Text translation (v2)
    Task<TextResult> TranslateTextAsync(
        string text, string sourceLanguage, string targetLanguage,
        string? options = null);

    Task<TextResult[]> TranslateTextBatchAsync(
        IEnumerable<string> texts, string sourceLanguage,
        string targetLanguage, string? options = null);

    // Glossary management (v2)
    Task<GlossaryInfo> CreateGlossaryAsync(
        string name, string sourceLang, string targetLang,
        Dictionary<string, string> entries);
    Task DeleteGlossaryAsync(string glossaryId);
    Task<GlossaryInfo> GetGlossaryAsync(string glossaryId);
    Task<GlossaryInfo[]> ListGlossariesAsync();
    Task<Dictionary<string, string>> GetGlossaryEntriesAsync(
        string glossaryId);

    // Style rules (v3)
    Task<StyleRuleResponse> CreateStyleRuleListAsync(
        string name, string language,
        JsonElement configuredRules,
        IEnumerable<CustomInstructionRequest> customInstructions);
    Task ReplaceConfiguredRulesAsync(
        string styleId, JsonElement configuredRules);
    Task<CustomInstructionResponse> AddCustomInstructionAsync(
        string styleId, string label, string prompt,
        string? sourceLanguage = null);
    Task DeleteCustomInstructionAsync(
        string styleId, string instructionId);
    Task DeleteStyleRuleListAsync(string styleId);

    // Usage tracking
    Task<Usage> GetUsageAsync();
    Task<Language[]> GetSourceLanguagesAsync();
    Task<Language[]> GetTargetLanguagesAsync();
}

Die Implementierung kümmert sich um die Normalisierung des Sprachcodes. DeepL erfordert EN-US oder EN-GB anstelle des bloßen en und PT-PT oder PT-BR anstelle von pt:

private static string NormalizeLanguageCode(string code)
    => code.ToLower() switch
    {
        "en" => "EN-US",
        "pt" => "PT-PT",
        _ => code.ToUpper()
    };

Die Batch-Übersetzung verwendet 50-Elemente-Chunking, um die API-Grenzen von DeepL einzuhalten und gleichzeitig den Durchsatz zu maximieren:

public async Task<TranslationBatchResult> TranslateBatchAsync(
    Dictionary<string, string> texts,
    string sourceLanguage, string targetLanguage)
{
    var translations = new Dictionary<string, string>();
    long totalChars = 0;

    foreach (var chunk in texts.Chunk(50))
    {
        var results = await _deepL.TranslateTextBatchAsync(
            chunk.Select(kv => kv.Value),
            sourceLanguage, targetLanguage);

        for (int i = 0; i < chunk.Length; i++)
        {
            translations[chunk[i].Key] = results[i].Text;
            totalChars += chunk[i].Value.Length;
        }
    }

    return new TranslationBatchResult
    {
        Translations = translations,
        BilledCharacters = totalChars
    };
}

Da wir nur veraltete Blöcke und nicht ganze Dokumente senden, enthält ein typischer Übersetzungsstapel für eine einzelne Bearbeitung 1-3 Blöcke statt 40+. Daher kommt die Kostenreduzierung von 94 %.

Der Übersetzungs-Orchestrator

Der TranslationOrchestrator entscheidet, was mit den einzelnen Blöcken geschehen soll, wenn sich das Quelldokument ändert. Schauen wir uns den Entscheidungsbaum an:

public async Task OrchestrateTranslationAsync(
    Guid entryId, List<Guid> changedBlockIds,
    CancellationToken ct = default)
{
    var entry = await _db.Entries
        .FirstOrDefaultAsync(e => e.Id == entryId, ct);

    var translations = await _db.EntryTranslations
        .Where(t => t.EntryId == entryId)
        .ToListAsync(ct);

    foreach (var translation in translations)
    {
        var langConfig = await GetLanguageConfigAsync(
            translation.Language, ct);

        var translationBlocks = await _db.TranslationBlocks
            .Where(tb => changedBlockIds.Contains(tb.SourceBlockId)
                      && tb.Language == translation.Language)
            .ToListAsync(ct);

        foreach (var block in translationBlocks)
        {
            if (block.IsLocked || block.TranslatedById is not null)
            {
                // Human-edited or locked - mark stale, don't overwrite
                block.Status = TranslationStatus.Stale;
            }
            else if (langConfig.Trigger == TranslationTrigger.AlwaysTranslate)
            {
                // Machine-translated, auto mode - retranslate now
                await RetranslateBlockAsync(block, translation.Language, ct);
            }
            else
            {
                // TranslateOnFirstVisit - mark stale, translate later
                block.Status = TranslationStatus.Stale;
            }
        }
    }

    await _db.SaveChangesAsync(ct);
}

Der wichtigste Punkt: Von Menschen bearbeitete Blöcke werden niemals automatisch überschrieben. Wenn ein Übersetzer einen Block manuell angepasst hat, z. B. durch Hinzufügen von kulturellem Kontext oder eine klarere Formulierung, respektiert das System diese Arbeit. Es markiert den Block als veraltet, damit der Übersetzer weiß, dass sich die Quelle geändert hat, aber es ersetzt seine Änderungen nicht stillschweigend.

Maschinell übersetzte Blöcke, bei denen AlwaysTranslate aktiviert ist, werden sofort neu übersetzt. Maschinell übersetzte Blöcke mit TranslateOnFirstVisit werden als veraltet markiert und übersetzt, wenn jemand das Dokument in dieser Sprache öffnet.

Übersetzungsauslöser: wann Übersetzungen stattfinden

Jede Sprache hat einen TranslationTrigger, der das Timing steuert:

public enum TranslationTrigger
{
    AlwaysTranslate,         // Translate on every save
    TranslateOnFirstVisit    // Translate when first opened in that language
}

AlwaysTranslate ist nützlich für Sprachen mit hoher Priorität, bei denen du möchtest, dass die Übersetzungen sofort aktuell sind. Französisch für ein Unternehmen mit einer großen Niederlassung in Paris. Deutsch für ein Unternehmen mit Hauptsitz in München.

TranslateOnFirstVisit ist nützlich für Sprachen, die gelegentlich gebraucht werden, aber die API-Kosten nicht wert sind, um sie immer auf dem neuesten Stand zu halten. Wenn jemand das Dokument in dieser Sprache öffnet, werden veraltete Blöcke sofort übersetzt.

Beide Modi verwenden die gleiche Glossarauflösung, die gleichen Formalitätseinstellungen und das gleiche Content-Hashing. Der einzige Unterschied ist das Timing.

Einzigartige Anpassung von Inhalt und Struktur

Hier zahlt sich die Architektur über die reine Übersetzung hinaus wirklich aus.

Wenn ein deutscher Übersetzer einen Abschnitt zur Einhaltung der DSGVO hinzufügt, den es im Englischen nicht gibt, fügt er ihn in der deutschen Version als neuen Block hinzu. Dieser Block hat keinen SourceBlockId, er ist als einzigartiger Inhalt gekennzeichnet. Das System schickt ihn nie zur Neuübersetzung, weil es keine Quelle gibt, aus der er übersetzt werden kann. Er existiert nur auf Deutsch.

Wenn ein japanischer Übersetzer eine Aufzählung in eine nummerierte Liste umwandelt (eine gängige Konvention in der japanischen Fachliteratur), bleibt das IsStructureAdapted-Kennzeichen des Blocks auch in zukünftigen Übersetzungszyklen erhalten:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    StructureAdaptationNotes = "Numbered list preferred in JP technical docs",
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

Das IsNoTranslate Flag behandelt Inhalte, die wortwörtlich kopiert werden sollen: Codeblöcke, URLs, Produktnamen, mathematische Notationen. Der Übersetzungsanbieter überspringt diese komplett.

Alles zusammenfügen

Gehen wir den gesamten Ablauf durch. Ein Benutzer in London bearbeitet einen Absatz im englischen Quelldokument, und dein Münchner Büro hat Deutsch auf AlwaysTranslate eingestellt:

Benutzer speichert. TipTap sendet JSON an die API.
Blockextraktion und Änderungserkennung. CreateBlocksFromDocumentAsync analysiert JSON, berechnet die Hashes der Inhalte neu und vergleicht die alten und neuen Hashes, um festzustellen, welche Blöcke sich tatsächlich geändert haben.
Orchestrator läuft. Findet den deutschen EntryTranslation, überprüft den deutschen Block. Er ist maschinell übersetzt, nicht gesperrt und nicht von Menschenhand bearbeitet, also kann er neu übersetzt werden.
**Übersetzungskonfiguration geladen ** Glossar-ID über GetOrSyncDeepLGlossaryIdAsync("en", "de") aufgelöst, Stilregeln über GetOrSyncStyleRuleListAsync("de"), Formalität auf "mehr" (formal "Sie") gesetzt, benachbarte Blöcke als Kontext für die Disambiguierung übergeben.
DeepL Aufruf. Ein einzelner Block wird mit Glossar-ID, Stil-ID, Formalität und Kontext gesendet.
Block aktualisiert. Übersetzter Inhalt gespeichert, SourceContentHash synchronisiert, Status auf UpToDate gesetzt. Ein Block anstelle von 40+ übersetzt. Die restlichen 39 Blöcke? Unangetastet.

In deinem Büro in Tokio ist Japanisch auf TranslateOnFirstVisit gesetzt. Die gleiche Bearbeitung markiert den japanischen Übersetzungsblock als Stale. Wenn jemand in Tokio das Dokument öffnet, werden die Schritte 5-9 im Handumdrehen ausgeführt. Ihre Strukturanpassung (nummerierte Liste) bleibt erhalten. Ihre einzigartigen Blöcke bleiben genau dort, wo sie sind.

Meiner Meinung nach ist die Übersetzungsmaschine der Teil von Rasepi, der den größten sichtbaren Nutzen bringt. Übersetzungen, die deine Terminologie verwenden, deine Formatierungskonventionen befolgen, deine eigenen Anweisungen befolgen, deinen Tonfall treffen, die Arbeit deiner Übersetzer respektieren und nur einen Bruchteil dessen kosten, was eine vollständige Neuübersetzung kosten würde. Die Architektur sorgt dafür, dass all das automatisch abläuft, und hält sich aus dem Weg, wenn Menschen die Arbeit übernehmen wollen.

Dieselbe DeepL Engine, die für die schriftlichen Übersetzungen zuständig ist, treibt auch Talk to Docs an, unsere dialogorientierte Dokumentationsschnittstelle, bei der DeepL Voice die gesprochene Interaktion übernimmt. Dieselben Glossare, dieselben Stilregeln, dieselbe Formalität, dieselbe Konsistenz. Ob dein Team die Dokumentation liest oder mit ihr spricht, die Sprachqualität ist identisch.

Erkunde die Übersetzungs-API →

Keine fünf Kopien desselben Dokuments mehr aufbewahren

2026-03-31T00:00:00Z

Öffne jetzt dein Unternehmens-Wiki und suche nach "Onboarding". Wie viele Ergebnisse erhältst du?

Wenn du ein globales Unternehmen bist, ist es vermutlich nicht eines. Es ist wahrscheinlich so etwas wie das hier:

Onboarding Guide (EN)
Onboarding Guide - Germany
Onboarding Guide - Japan
Onboarding LATAM (draft)
Onboarding - New (DO NOT USE OLD ONE)

Fünf Dokumente. Alle behandeln ungefähr die gleiche Sache. Alle leicht unterschiedlich. Alle werden von verschiedenen Leuten nach unterschiedlichen Zeitplänen gepflegt. Manche sind aktuell, manche liegen drei Monate zurück, bei einem ist sich niemand mehr sicher.

Das passiert, wenn deine Dokumentationsplattform nicht richtig mit mehrsprachigen Inhalten umgehen kann. Am Ende kopierst du das gesamte Dokument für jeden Markt, und jede Kopie entfernt sich langsam von den anderen.

Ein Dokument, alle Sprachen](/de/blog/img/ein-dokument-alle-sprachen.svg)

Die Kopier- und Lokalisierungsfalle

Es fängt eigentlich ganz harmlos an. Du hast einen tollen Onboarding-Leitfaden auf Englisch. Das Berliner Büro braucht ihn auf Deutsch, also kopiert ihn jemand, übersetzt ihn und fügt die deutschsprachigen Teile hinzu: DSGVO-Schulung, Informationen zum Betriebsrat, Anmeldung bei der örtlichen Krankenversicherung.

Dann braucht Tokio einen. Wieder kopieren. Übersetze. Füge die japan-spezifischen Dinge hinzu: Hanko-Registrierung, Pendlerpass-Verfahren, Büro-Knigge-Leitfaden.

São Paulo ist als nächstes dran. Das Gleiche. Kopieren, übersetzen, lokale Inhalte über CLT-Anforderungen, Essensgutscheine und Steuerdokumente hinzufügen.

Jetzt hast du vier Dokumente. Das englische Original wird regelmäßig aktualisiert. Die deutsche Version wurde im letzten Quartal aktualisiert. Die japanische Version... jemand glaubt, dass Tanaka-san sie im Oktober aktualisiert hat. Die brasilianische Version wurde von einem Auftragnehmer erstellt, der sie verlassen hat, und seitdem hat sie niemand mehr angefasst.

Jedes Exemplar ist ein Wartungsaufwand, und jedes enthält eine Mischung aus gemeinsamen Inhalten (die überall gleich sind) und lokalen Inhalten (die für den jeweiligen Markt spezifisch sind). Aber die Plattform kennt den Unterschied nicht. Es ist alles nur Text auf einer Seite.

Wenn also jemand den Abschnitt über die Sicherheitsrichtlinien im englischen Original aktualisiert, werden die anderen vier nicht aktualisiert. Oder schlimmer noch, jemand aktualisiert den deutschen Teil, aber nicht den japanischen. Jetzt hast du fünf Dokumente, die alle leicht unterschiedliche Dinge über dieselbe Unternehmenspolitik aussagen.

Das eigentliche Problem: Gemeinsame und lokale Inhalte werden vermischt

Das Problem ist, dass die meisten dieser Dokumente zu 70-80% identisch sind. Die Einführungsschritte, die Einrichtung der Tools, die Sicherheitsrichtlinien, der Abschnitt über die Unternehmenswerte, die Liste der Ansprechpartner. Das ist alles dasselbe, egal ob du in Berlin, Tokio oder São Paulo sitzt.

Der lokale Teil macht vielleicht 20-30% des Dokuments aus. Spezifische Compliance-Anforderungen, lokale Vorteile, regionale Prozesse, Teamkontakte für das jeweilige Büro.

Aber wenn alles in einem großen, flachen Dokument pro Sprache steht, gibt es keine Möglichkeit zu erkennen, welche Teile gemeinsam genutzt werden und welche lokal sind. Eine Aktualisierung des gemeinsamen Inhalts bedeutet, dass man jede Kopie manuell überprüfen und aktualisieren muss. Und das macht niemand konsequent. Deshalb wandern deine Kopien ab.

Ein Dokument. Das war's.

In Rasepi ist der Onboarding-Leitfaden ein einziges Dokument. Nicht eines pro Sprache. Ein einziges.

Die gemeinsamen Inhalte, die 70-80%, die überall gleich sind, werden einmal auf Englisch geschrieben und automatisch in jede Sprache übersetzt, die dein Team verwendet. Wenn jemand den Abschnitt über die Sicherheitsrichtlinien auf Englisch aktualisiert, wird er innerhalb von Sekunden ins Deutsche, Japanische, Portugiesische und Französische übersetzt. Kein manuelles Kopieren. Kein "Jemand sollte die anderen Versionen aktualisieren".

Der lokale Inhalt lebt in der jeweiligen Sprachversion. Der DSGVO-Schulungsteil existiert nur in der deutschen Version. Der Hanko-Prozess existiert nur in der japanischen Version. Die CLT-Anforderungen gibt es nur in der portugiesischen Version. Diese Abschnitte sind als einzigartige Inhalte gekennzeichnet, sie gehören zu dieser Sprache und werden niemals durch eine Neuübersetzung überschrieben.

Wie das genau funktioniert, haben wir in unserem Beitrag Wie Rasepi-Übersetzungen funktionieren beschrieben. Die Kurzversion: Jeder Absatz hat seine eigene Identität. Gemeinsame Absätze werden übersetzt und nachverfolgt. Einzigartige Absätze gehören zu ihrer Sprache und nichts anderes berührt sie.

Das Ergebnis? Deine Wiki-Suche nach "Onboarding" liefert nur ein Ergebnis. Nur "Onboarding". Öffnest du es auf Englisch, siehst du die englische Version mit allen gemeinsamen Inhalten. Öffnest du sie auf Deutsch, siehst du dieselben gemeinsamen Inhalte auf Deutsch plus die deutschsprachigen Abschnitte. Öffne sie auf Japanisch, dann siehst du dieselben gemeinsamen Inhalte auf Japanisch und die japanischen Abschnitte.

Ein Dokument. Nicht fünf. Nicht fünf Dokumente, die langsam und mit unterschiedlicher Geschwindigkeit verrotten.

Was dies tatsächlich ändert

Das ist nicht nur aufgeräumter. Es verändert grundlegend, wie deine Dokumentation in den verschiedenen Büros funktioniert.

Aktualisierungen erreichen tatsächlich jeden.

Wenn du den gemeinsamen Teil des Onboarding-Leitfadens aktualisierst, wird er in allen Sprachen auf den neuesten Stand gebracht. Nicht erst, wenn sich jemand daran erinnert, es zu tun. Er wird automatisch aktualisiert. Der Absatz, den du geändert hast, wird neu übersetzt. Alles andere bleibt genau so, wie es war.

Das bedeutet, dass dein Büro in Tokio die gleichen Unternehmensrichtlinien liest wie dein Büro in London. Nicht die Version von vor sechs Monaten, die niemand aktualisieren konnte.

Lokale Teams besitzen ihre lokalen Inhalte

Dein Münchner Team kann einen Abschnitt über den lokalen Fitnessstudio-Rabatt hinzufügen, ohne sich Sorgen machen zu müssen, dass er durch das nächste englische Update ausgelöscht wird. Ihre einzigartigen Inhalte gehören ihnen. Er verbleibt in der deutschen Version und wird von Änderungen an der englischen Version nicht berührt.

Dasselbe gilt für jedes andere Büro. Lokale Inhalte sind wirklich lokal. Sie haben keinen Einfluss auf die gemeinsamen Inhalte und die gemeinsamen Inhalte haben keinen Einfluss auf sie.

Neu eingestellte Mitarbeiter erhalten die richtigen Informationen

Ein neuer Mitarbeiter in São Paulo öffnet den Einführungsleitfaden und sieht alles, was er braucht. Die gemeinsamen Abschnitte (Tools, Sicherheit, Werte) sind auf Portugiesisch. Die brasilienspezifischen Abschnitte (CLT, Steuerdokumente, Essensgutscheine) sind gleich daneben. Ein Dokument, alles in ihrer Sprache, nichts fehlt, nichts ist veraltet.

Sie müssen nicht wissen, dass drei andere Büros andere lokale Abschnitte haben. Sie sehen nur ihre Version. Sauber und vollständig.

Deine Seitenzahl sinkt

Das ist die einfache Rechnung. Wenn du 50 wichtige Dokumente hast und sie in 5 Sprachen mit dem Copy-and-Localise-Ansatz pflegst, hast du 250 Dokumente. In Rasepi hast du 50. Jede dieser Sprachversionen hat einen gemeinsamen Inhalt und ihre eigenen lokalen Abschnitte.

250 Dokumente müssen gepflegt werden, statt 50. Das sind 200 Seiten Wartungsaufwand, die einfach verschwinden.

Es geht nicht nur um das Onboarding

Onboarding ist das offensichtliche Beispiel, weil jedes globale Unternehmen dieses Problem hat. Aber das gleiche Muster ist überall zu beobachten:

Einführungsleitfäden. Die Kernschritte sind die gleichen, aber das Berliner Team verwendet einen lokalen Staging-Server und Tokio hat einen anderen Genehmigungsprozess.
Compliance-Dokumentation. GDPR-Abschnitt für Europa, LGPD für Brasilien, APPI für Japan. Alle befinden sich im selben Dokument und werden nur dort angezeigt, wo sie relevant sind.
Vergünstigungen und Personalpolitik. Die Elternzeitregelung ist in jedem Land anders. Die Unternehmenswerte sind überall dieselben.
Kundenorientierte Hilfedokumente. Das Produkt funktioniert überall gleich, aber die Zahlungsmodalitäten, die Supportzeiten und die regionalen Bestimmungen sind unterschiedlich.

Jedes dieser Dokumente ist ein Dokument, das die meisten Unternehmen für jeden Markt separat pflegen. Und jedes dieser Dokumente könnte ein einziges Dokument mit gemeinsamen und lokalen Inhalten sein.

Der Verbundeffekt

Hier wird es ernst. Ein Unternehmen mit 200 Dokumenten in 4 Märkten pflegt nicht nur 200 Dokumente. Es verwaltet 800. Aber sie haben Personal für 200. Was also tatsächlich passiert, ist:

Die englischen Versionen sind aktuell
Die deutschen Versionen sind meist aktuell
Die französischen Versionen sind im Rückstand
Die japanischen Versionen sind ein Fragezeichen

Kommt dir das bekannt vor?

In Rasepi verwalten sie 200 Dokumente. Die gemeinsamen Inhalte werden automatisch übersetzt. Die lokalen Inhalte werden von den lokalen Teams hinzugefügt. Jede Version ist so aktuell wie die englische, plus die lokalen Ergänzungen, die das regionale Team vorgenommen hat.

Auch die Übersetzungskosten sind niedriger. Wenn du einen Absatz in Englisch aktualisierst, wird nur dieser Absatz in alle Sprachen neu übersetzt. Nicht das ganze Dokument, nicht alle 200 Dokumente. Nur der Absatz, der sich tatsächlich geändert hat. Wir haben ausführlich darüber geschrieben wie das funktioniert, einschließlich des Glossars und der Stilregeln, die dafür sorgen, dass übersetzte Inhalte natürlich klingen.

Ein kurzer Bauchcheck

Wenn du ein globales Team leitest, solltest du dich fragen:

Wie viele doppelte Dokumente hast du? Suche nach demselben Thema und zähle die sprachspezifischen Kopien.
Wie aktuell sind die nicht-englischen Versionen? Überprüfe das Datum der letzten Änderung in deinen deutschen, französischen oder japanischen Dokumenten. Wie weit liegen sie zurück?
Fügen die Teams vor Ort Inhalte zu ihren Versionen hinzu? Oder haben sie es aufgegeben, weil sie überschrieben werden?
Wie lange dauert das Onboarding in den nicht-englischen Büros? Wenn es länger dauert, ist es wahrscheinlich, dass die Dokumentation für sie nicht richtig ist.

Wenn du dich bei den Antworten unwohl fühlst, bist du nicht allein. Die meisten Unternehmen merken erst dann, wie viel Aufwand sie verursacht haben, wenn sie die Kopien tatsächlich zählen.

Die Dokumentation sollte mit deinem Unternehmen mitwachsen und sich nicht vervielfältigen. Jedes Exemplar, das du pflegst, ist ein Exemplar, das zurückbleiben, einen neuen Mitarbeiter verwirren oder der Version widersprechen kann, die jemand anderes gerade liest. Ein Dokument pro Thema, mit übersetzten gemeinsamen Inhalten und lokalen Inhalten, wo sie hingehören - so sollte die Dokumentation in einem globalen Unternehmen funktionieren.

Dein Wiki sollte nicht fünf Kopien desselben Dokuments benötigen. Eine ist genug. Gemeinsame Schritte übersetzt, lokale Schritte pro Sprache. Das war's.

Siehe mehrsprachige Veröffentlichung in Aktion →

Der Business Case für Block-Level-Lokalisierung

2026-03-24T00:00:00Z

In jedem Unternehmen, das grenzüberschreitend tätig ist, gibt es ein Muster. Die englische Dokumentation ist solide. Die deutsche Version ist drei Monate im Rückstand. Die japanische Version wurde einmal von einem Auftragnehmer übersetzt, und seitdem hat sie niemand mehr angefasst. Die brasilianisch-portugiesische Version gibt es noch nicht, obwohl São Paulo das am schnellsten wachsende Büro ist.

Alle sind sich einig, dass dies ein Problem ist. Niemand hat eine gute Lösung. Bisher wurde die Lokalisierung als ein Projekt behandelt, eine einmalige Anstrengung, die man einplant, durchführt und dann bis zur nächsten großen Überarbeitung vernachlässigt.

Dieser Ansatz ist nicht mehr zeitgemäß. Hier ist der Grund dafür und was meiner Meinung nach wirklich funktioniert.

Übersetzung ist keine Lokalisierung

Lass uns die Terminologie klären. Übersetzen bedeutet, einen Text in einer Sprache in einen gleichwertigen Text in einer anderen Sprache zu übertragen. Lokalisierung bedeutet, Wissen für einen bestimmten Markt nutzbar zu machen. Es gibt Überschneidungen, aber sie sind nicht dasselbe.

Ein übersetztes Dokument liest sich korrekt. Ein lokalisiertes Dokument liest sich natürlich. Es berücksichtigt den kulturellen Kontext, regionale Vorschriften, lokale Werkzeuge und die Art und Weise, wie die Menschen in diesem Markt tatsächlich arbeiten.

Diese Unterscheidung ist wichtig, weil die meisten Dokumentationsplattformen die Lokalisierung als eine Übersetzungsaufgabe behandeln. Du schreibst auf Englisch, drückst auf einen Knopf und bekommst die Ausgabe auf Französisch. Das war's. Aber es ist nicht erledigt, denn:

Das französische Team hat einen anderen Bereitstellungsprozess, den die englische Dokumentation nicht abdeckt.
Die deutschen Compliance-Anforderungen fügen einen zusätzlichen Genehmigungsschritt hinzu, den es anderswo nicht gibt.
Das japanische Büro verwendet ein anderes internes Tool für denselben Arbeitsablauf.
die brasilianisch-portugiesischen Leser einen Kontext zu den lokalen Steuervorschriften benötigen, der nirgendwo anders relevant ist

**Eine reine Übersetzung des englischen Dokuments ist in all diesen Fällen technisch korrekt und in allen Fällen praktisch nutzlos.

Das Problem mit der Übersetzung auf Dokumentenebene

Die herkömmliche Lokalisierung funktioniert auf der Dokumentenebene. Du hast ein englisches Dokument. Du übersetzst das gesamte Dokument ins Deutsche. Wenn sich die englische Version ändert, schickst du das gesamte Dokument zur Neuübersetzung. Das schafft drei Probleme:

1. Es ist teuer

Wenn dein Einführungshandbuch 15 Abschnitte hat und du einen Absatz änderst, musst du alle 15 Abschnitte neu übersetzen. Multipliziere das mit 8 Sprachen und jede Änderung wird zu einer Budgetdiskussion.

2. Es ist langsam

Komplette Dokumente zur Übersetzung zu schicken, braucht Zeit. Selbst mit moderner maschineller Übersetzung ist der Überprüfungszyklus für ein komplettes Dokument deutlich länger als für einen einzelnen geänderten Abschnitt. Teams in anderen Sprachen sind immer im Verzug.

3. Es werden keine einzigartigen Inhalte unterstützt

Das ist der wahre Killer. Wenn die deutsche Version einen zusätzlichen Abschnitt über die Einhaltung der DSGVO braucht, wo kommt der dann hin? In einem Übersetzungssystem auf Dokumentenebene wird jeder Inhalt, der der deutschen Version hinzugefügt wird, bei der nächsten Neuübersetzung aus dem Englischen überschrieben. Das deutsche Team lernt schnell: Füge nichts hinzu, weil es sonst gelöscht wird.

Lokalisierung auf Blockebene: eine andere Architektur

Rasepi übersetzt keine Dokumente. Es übersetzt Blöcke: einzelne Absätze, Überschriften und Abschnitte, die jeweils unabhängig voneinander mit einer eigenen Identität und einem Inhaltshash verfolgt werden.

In der Praxis bedeutet das Folgendes:

Wenn du einen einzelnen Absatz auf Englisch bearbeitest, erkennt Rasepi durch den Vergleich von SHA256-Inhaltshashes, welcher Block sich geändert hat. Nur dieser eine Block wird zur Übersetzung über DeepL gesendet. Die anderen 14 Blöcke des Dokuments bleiben genau so, wie sie waren. Deine Übersetzungskosten sinken um bis zu 94%.

Wenn der deutsche Übersetzer einen DSGVO-Abschnitt hinzufügen muss, fügt er ihn als neuen Block in die deutsche Version ein. Dieser Block existiert nur auf Deutsch. Er hat keinen Einfluss auf den englischen Quelltext. Er wird nicht überschrieben, wenn sich die englische Version ändert. Er ist als einzigartiger Inhalt gekennzeichnet, damit jeder weiß, dass er beabsichtigt ist.

Wenn die japanische Version eine andere Struktur braucht, z. B. eine nummerierte Liste statt Aufzählungspunkten, weil das in der japanischen Fachliteratur üblich ist, kann der Übersetzer den Blocktyp ändern. Das System merkt sich dies als "Strukturanpassung" und behält sie bei zukünftigen Aktualisierungen bei.

Jede Sprachversion wird zu einem Dokument erster Klasse, nicht zu einer Schattenkopie.

So funktioniert es, technisch gesehen

Jeder Block in Rasepi hat:

Eine UUID, die über alle Bearbeitungen und Übersetzungen hinweg bestehen bleibt
Einen Inhalts-Hash (SHA256), der sich ändert, wenn sich der Text ändert
einen Positionsindex**, damit die Blöcke in der richtigen Reihenfolge bleiben
Ein Soft-Delete-Flag, damit das Entfernen eines Blocks auf Englisch die Ausrichtung in anderen Sprachen nicht beeinträchtigt

Wenn ein Übersetzungsblock erstellt wird, speichert er den Inhaltshash des Ausgangsblocks. Bei jedem Speichern vergleicht das System die Hashes. Wenn sie übereinstimmen, ist die Übersetzung aktuell. Wenn sie nicht übereinstimmen, wird die Übersetzung als veraltet markiert, und nur der betreffende Block muss bearbeitet werden.

Das ist der Mechanismus, der die Kosten um 94 % senkt. Die meisten Bearbeitungen ändern einen oder zwei Abschnitte. Der Rest des Dokuments bleibt in allen Sprachen unangetastet.

Einzigartiger Inhalt pro Sprache

Hier unterscheiden sich die Dinge wirklich von allen anderen Plattformen.

In Rasepi kann jede Sprachversion enthalten:

Übersetzte Blöcke. Direkte Übersetzungen der Ausgangssprache, die auf ihre Aktualität hin überprüft werden
Einzigartige Blöcke. Inhalte, die es nur in dieser Sprache gibt und die vom lokalen Team hinzugefügt wurden
Strukturangepasste Blöcke. Gleicher Quellinhalt, andere Formatierung oder Blocktyp

Ein einzelnes Dokument könnte in allen Sprachen so aussehen:

Block	Englisch (Quelle)	Deutsch	Japanisch
1	Einleitung	Übersetzt	Übersetzt
2	Einrichtungsschritte	Übersetzt	Struktur angepasst (nummerierte Liste)
3	-	DSGVO-Konformität (eindeutig)	-
4	Einsatz	Übersetzt	Übersetzt
5	-	-	Lokale Tooling-Hinweise (einmalig)
6	Fehlersuche	Übersetzt	Übersetzt

Jedes Team bekommt genau die Dokumentation, die es braucht. Keine Kompromisse. Keine Umgehungslösungen. Keine Einheitsgröße, die für alle passt.

Freshness Tracking über alle Sprachen hinweg

Jede Sprachversion verfolgt ihre eigene Aktualität unabhängig. Die englische Quelle könnte 94 Punkte erreichen (kürzlich überprüft, alle Links gültig, hohe Leserschaft). Die französische Version könnte 71 Punkte erreichen (zwei veraltete Blöcke, ein defekter Link speziell für den französischen Inhalt). Die japanische Version könnte 88 Punkte erreichen (alle Übersetzungen sind aktuell, aber die Leserschaft ist rückläufig).

Dieses Freshness-Tracking für jede Sprache bedeutet:

Du weißt genau, welche Sprachen Aufmerksamkeit brauchen.
Veraltete Übersetzungen werden automatisch aufgedeckt und nicht durch Zufall entdeckt.
KI-Tools können die sprachspezifische Aktualität bei der Bereitstellung von Antworten berücksichtigen
Dashboards zeigen den Zustand der Inhalte aufgeschlüsselt nach Sprachen und nicht nur nach Dokumenten.

Der Business Case

Unternehmen, die sprachübergreifend tätig sind, sehen sich mit einer einfachen Tatsache konfrontiert: Ihre Dokumentation ist in jedem Markt, den Sie bedienen, entweder ein Vorteil oder eine Belastung.

Wenn dein Berliner Team mit einer deutschen Übersetzung arbeitet, die dem englischen Original drei Monate hinterherhinkt, trifft es seine Entscheidungen auf der Grundlage veralteter Informationen. Wenn dein Büro in Tokio den gemeinsam genutzten Dokumenten keinen lokalen Kontext hinzufügen kann, weil das Übersetzungssystem ihn überschreiben würde, nutzt es das Wiki nicht mehr und erstellt seine eigene Schattendokumentation. Wenn dein Team in São Paulo überhaupt keine Dokumente auf Portugiesisch hat, dauert das Onboarding doppelt so lange.

Die Kosten sind nicht nur die Übersetzungskosten. Sondern auch:

Langsameres Onboarding in nicht-englischen Märkten
Doppelter Aufwand, da die Teams parallele Dokumentationen in lokalen Tools pflegen
Wissenssilos, die sich bilden, wenn das offizielle Wiki nicht allen zur Verfügung steht
Compliance-Risiko, wenn regionalspezifische Anforderungen nicht erfasst werden
Verlust des Vertrauens in das Dokumentationssystem selbst

Die Lokalisierung auf Blockebene löst all diese Probleme, und zwar nicht, indem sie die Übersetzung billiger macht (obwohl sie das tut), sondern indem sie jede Sprachversion zu einem lebendigen, gepflegten und vertrauenswürdigen Dokument macht.

Erste Schritte

Wenn du heute ein mehrsprachiges Team auf einer beliebigen Dokumentationsplattform betreibst, hier ein kurzer Bauchcheck:

Wähle dein wichtigstes Dokument aus. Überprüfe es in jeder Sprache. Ist jede Version aktuell?
Befrag deine nicht-englischen Teams: Vertrauen sie den übersetzten Dokumenten? Benutzen sie sie?
Suche nach Schattendokumentation. Pflegen Teams lokale Wikis, Notion-Seiten oder Slack-Pinnachrichten, weil ihnen die offiziellen Dokumente nicht ausreichen?
Berechne deine Ausgaben für Übersetzungen. Wie viel zahlst du pro Update und wie viel davon ist die Neuübersetzung von Inhalten, die sich nicht geändert haben?

Wenn die Antworten unangenehm sind, bist du nicht allein. Die meisten Unternehmen entdecken die Lücke erst, wenn sie ein echtes Problem verursacht: ein Problem mit der Einhaltung von Vorschriften, eine verpatzte Implementierung, ein neuer Mitarbeiter, der zwei Wochen lang veraltete Anweisungen befolgt hat.

Mehrsprachige Kenntnisse sind kein Nice-to-have. Für jedes Unternehmen, das grenzüberschreitend tätig ist, ist es die Grundlage dafür, wie sich Teams abstimmen, Entscheidungen treffen und Lieferungen durchführen. Die Frage ist, ob deine Dokumentationsplattform das auch so handhabt.

Jede Sprache verdient es, ein erstklassiger Bürger in deiner Wissensdatenbank zu sein. Keine Kopie. Kein Schatten. Ein echtes, gepflegtes, vertrauenswürdiges Dokument.

Das ist es, was Rasepi liefert. Übersetzung auf Blockebene, einzigartiger Inhalt pro Sprache, unabhängige Verfolgung der Aktualität und eine 94%ige Reduzierung der Übersetzungskosten. Alles automatisch. Und das vom ersten Tag an.

Mehrsprachiges Publizieren in Aktion sehen →

Frische der Inhalte, Teil 2: Jenseits von Verfallsdaten

2026-03-18T00:00:00Z

*Dies ist Teil 2 unserer Serie über die Frische von Inhalten. [In Teil 1 (/de/blog/why-freshness-matters-more-than-ever/) haben wir erklärt, warum Frische wichtig ist und was sie eigentlich bedeutet. Dieser Beitrag macht da weiter, wo er aufgehört hat: warum Verfallsdaten allein nicht ausreichen und wie eine kontinuierliche Überwachung aussieht.

Nehmen wir an, du tust etwas Verantwortungsvolles. Jedes Dokument in deinem Wiki bekommt ein Verfallsdatum. Sechs Monate nach der Erstellung, vielleicht zwölf für stabiles Referenzmaterial. Wenn das Datum erreicht ist, erhält der Eigentümer eine Benachrichtigung: Überprüfe das Dokument oder es wird markiert.

Das ist besser als das, was die meisten Unternehmen tun. Die meisten Unternehmen tun nichts. Die Dokumente verrotten langsam und niemand merkt es, bis jemand die Anweisungen befolgt und etwas kaputt geht.

Aber hier ist die unbequeme Wahrheit: Verfallsdaten sind notwendig und völlig unzureichend. Ich habe Dokumente gesehen, die schon Tage nach ihrer letzten Überprüfung gefährlich veraltet sind, und ein Überprüfungsdatum kann das nicht auffangen.

Was Verfallsdaten wirklich lösen

Verfallsdaten lösen das Problem der Rechenschaftspflicht. Sie beantworten die Frage: _"Wer ist dafür verantwortlich, dass das Datum noch stimmt und wann?" _

Das ist wirklich wertvoll. Ohne ein solches Datum geraten die Unterlagen in das sogenannte "Ownership Void", einen Zustand, in dem jeder davon ausgeht, dass jemand anderes sie pflegt, und es daher niemand tut. Durch die Festlegung eines Überprüfungsdatums wird einer einzelnen Person eine Verpflichtung zu einem bestimmten Datum auferlegt. Einfach. Klar. Effektiv.

So sehen Verfallsdaten in der Praxis aus:

Ein Dokument wird mit einem Überprüfungsdatum in 90 Tagen erstellt
14 Tage vor Ablauf wird der Eigentümer benachrichtigt
Am Verfallsdatum wird das Dokument als "zu überprüfen" gekennzeichnet.
Der Eigentümer überprüft das Dokument, bestätigt, dass es noch korrekt ist, und verlängert das Datum.
Oder er aktualisiert es, ordnet es neu zu oder archiviert es.

Dies ist ein solides System. Es fängt den langsamen Verfall auf, die Dokumente, an die seit einem Jahr niemand mehr gedacht hat. Es schafft einen regelmäßigen Rhythmus der Überprüfung. Es macht die Verantwortung sichtbar.

Aber es hat einen blinden Fleck von der Größe eines Kontinents.

Was Verfallsdaten verpassen

Zwischen den Überprüfungsterminen lebt ein Dokument in einer Blackbox. Du hast es am 15. Januar überprüft. Die nächste Überprüfung ist am 15. April. Am 3. Februar könnte alles Mögliche passieren:

Links brechen stillschweigend ab

Eine externe URL, auf die du verwiesen hast, gibt eine 404 zurück. Ein interner Link verweist auf ein Dokument, das archiviert wurde. Ein Code-Repository wurde umbenannt und jeder GitHub-Link in deinem Dokument ist jetzt tot. Dein Dokument sieht noch gut aus. Das Verfallsdatum ist erst in zwei Monaten. Niemand weiß, dass die Links kaputt sind.

Die Leserschaft sinkt auf Null

Dein Dokument wurde früher von 40 Personen pro Monat gelesen. Dann hat sich ein Prozess geändert und niemand braucht es mehr, aber niemand hat es auch archiviert. Es steht in den Suchergebnissen, nimmt Platz weg und verwirrt gelegentlich einen neuen Mitarbeiter, der nicht weiß, dass es irrelevant ist. Das Verfallsdatum kümmert sich nicht um die Leserschaft. Es pingt den Besitzer trotzdem pünktlich an.

Übersetzungen geraten ins Hintertreffen

Die englische Quelle wurde am 10. Februar aktualisiert. Die französischen, deutschen und japanischen Übersetzungen sind jetzt veraltet. Aber das Verfallsdatum dieser übersetzten Versionen ist erst im Mai. Drei Monate lang lesen die nicht-englischen Teams veraltete Inhalte und wissen es nicht.

Leser weisen auf Probleme hin

Ein Leser hinterlässt einen Kommentar: "Schritt 3 funktioniert nicht mehr, das CLI-Flag wurde abgeschafft." Dieser Kommentar steht da. Das Verfallsdatum ist noch Wochen entfernt. Die nächste Person, die die Dokumentation liest, sieht den Kommentar vielleicht nicht. Die Person, die danach kommt, bestimmt nicht.

Das Verfallsdatum ist ein geplanter Kontrollpunkt. Dies sind ungeplante Ereignisse. In der Lücke dazwischen richtet veraltete Dokumentation den größten Schaden an.

Frische: kontinuierliche Überwachung

Die Freshness-Bewertung füllt die Lücke, die das Verfallsdatum offen lässt. Anstatt den Zustand eines Dokuments einmal alle 90 Tage zu überprüfen, wird es mit Freshness kontinuierlich überwacht. Jeden Tag, im Hintergrund, ohne dass jemand etwas tun muss.

So funktioniert es in Rasepi:

Jedes Dokument erhält einen Live-Freshness-Score von 0 bis 100, der aus mehreren Signalen berechnet wird:

Signal	Was es erkennt	Warum es wichtig ist
Link-Gesundheit	Kaputte, umgeleitete oder unerreichbare URLs	Kaputte Links untergraben das Vertrauen und verschwenden Zeit
Review-Status	Ob das Dokument fristgerecht überprüft wurde	Die grundlegende Überprüfung der Verantwortlichkeit
Lesertrends	Ob es überhaupt jemand liest	Geringe Leserzahlen deuten darauf hin, dass das Dokument irrelevant sein könnte
Bearbeitungszeitpunkt	Wann das Dokument zuletzt geändert wurde im Vergleich zu verwandten Inhalten	Erkennt eine Abweichung von der umgebenden Wissensbasis
Übersetzungs-Alignment	Ob alle Sprachversionen aktuell sind	Veraltete Übersetzungen bedeuten, dass Teams in anderen Märkten mit alten Informationen arbeiten
Leserkennzeichen	Ob Leser Probleme gemeldet haben	Crowdsourced Staleness Detection
Querverweise	Ob die Dokumente, auf die verlinkt wird, selbst veraltet sind	Veraltetheit ist ansteckend

Jedes Signal trägt zur Gesamtbewertung bei. Ein Dokument kann wegen eines defekten Links heute Frischepunkte verlieren, auch wenn das Überprüfungsdatum erst in Wochen ist. Das ist der springende Punkt.

Wie die beiden zusammenarbeiten

Verfall und Frische sind keine konkurrierenden Ansätze. Sie sind komplementäre Ebenen:

Das Verfallsdatum ist die Steuerungsebene. Sie sorgen für eine regelmäßige Überprüfung durch Menschen. Jemand muss sich das Dokument regelmäßig ansehen und bestätigen, dass es noch aktuell ist. Damit werden die Dinge erfasst, die die Automatisierung nicht kann: ob der Inhalt noch stimmt, ob die Ratschläge noch fundiert sind, ob der beschriebene Prozess noch der Realität entspricht.

Die Frischheitsbewertung ist die Überwachungsebene. Sie erfasst alles, was zwischen den Überprüfungszeitpunkten passiert: defekte Links, abweichende Übersetzungen, verlassene Dokumente, den kontextuellen Verfall, der eintritt, wenn sich die Welt verändert, ein Dokument aber nicht.

Gemeinsam schaffen sie ein System, in dem:

Jedes Dokument wird in regelmäßigen Abständen von einem Menschen überprüft (Verfall)
Zwischen den Überprüfungen fangen automatische Signale Probleme ab, sobald sie auftreten (Aktualität).
Beide Systeme fließen in eine einzige Vertrauensbewertung ein, die jeder sehen kann
Dieser Wert beeinflusst, wie das Dokument in der Suche eingestuft wird und ob KI-Tools es als Quelle nutzen

Die Auswirkungen des Scorings

Hier wird es praktisch. In Rasepi wirkt sich der Freshness Score eines Dokuments direkt auf seine Sichtbarkeit aus:

Score 80-100: Volle Sichtbarkeit. Erscheint normal in den Suchergebnissen. Kommt als Quelle für KI-Antworten in Frage. Keine Markierungen.
Punktzahl 50-79: Eingeschränkte Sichtbarkeit. Erscheint in den Suchergebnissen mit einem Veralterungsindikator. KI-Tools können ihn als Quelle zurückstufen. Der Eigentümer wird benachrichtigt.
Punktzahl unter 50: Markiert. Wird in den Suchergebnissen deutlich nach unten verschoben. Ganz von den KI-Antworten ausgeschlossen. Der Eigentümer erhält eine dringende Benachrichtigung.

So entsteht eine Feedbackschleife. Wenn die Punktzahl eines Dokuments sinkt, wird der Eigentümer dazu gedrängt, das Problem zu beheben, und zwar nicht, weil ein beliebiges Datum erreicht wurde, sondern weil sich tatsächlich etwas geändert hat. Der defekte Link, die veraltete Übersetzung, die sinkende Leserschaft - das sind echte Signale, die jetzt beachtet werden müssen, nicht erst in sechs Wochen.

Ein praktisches Beispiel

Gehen wir mal ein Szenario durch:

März 1: Dein "Incident Response Playbook" erreicht 92 Punkte. Es wurde vor zwei Wochen überprüft, alle Links sind gültig, die Leserschaft ist hoch und alle vier Sprachversionen sind aktuell.

März 8: Jemand strukturiert die Status-Seite der Technik um. Drei URLs im Playbook leiten jetzt um. Der Freshness Score sinkt auf 78. Der Besitzer erhält eine Benachrichtigung: "3 defekte Links entdeckt."

März 10: Der Besitzer repariert die Links. Der Wert steigt wieder auf 89.

März 15: Die englische Version wird mit einem neuen Eskalationspfad aktualisiert. Die französischen und deutschen Übersetzungen sind jetzt veraltet (Hash-Mismatch). Die Punktzahl fällt auf 74.

März 17: Die Übersetzungen wurden aktualisiert. Die Punktzahl steigt wieder auf 91.

März 20: Die Leserschaftsdaten zeigen, dass die japanische Version seit 30 Tagen nicht mehr aufgerufen wurde. Die Punktzahl sinkt auf 86. Ein subtiles Signal, das aber verfolgt wird.

April 1: Der geplante Überprüfungstermin ist da. Der Eigentümer überprüft den Inhalt, bestätigt, dass er korrekt ist, und verlängert die Frist bis zum 1. Juli. Die Punktzahl bleibt bei 86, weil das Signal der Leserschaft immer noch vorhanden ist.

Das Team hat zu keinem Zeitpunkt auf ein Überprüfungsdatum gewartet, um ein Problem zu erkennen. Das Frischesystem zeigte Probleme innerhalb weniger Tage an. Das Überprüfungsdatum war der Kontrollpunkt für die Verwaltung. Beide Ebenen tun ihre Arbeit.

Warum "nur ein Überprüfungsdatum festlegen" nicht mehr ausreicht

Vor fünf Jahren waren Verfallsdaten vielleicht noch ausreichend. Die Dokumentation wurde von Menschen gelesen, und die Menschen konnten sich ein Urteil bilden. Wenn ein Dokument nicht ganz stimmig war, hat man sich umgehört.

Heute ist die Dokumentation eine Infrastruktur. Sie speist KI-Tools, Onboarding-Automatisierung, Compliance-Systeme und Suchmaschinen, die Ergebnisse ohne Kontext liefern. Diese Systeme sind nicht in der Lage, sich ein Urteil zu bilden. Sie konsumieren die Inhalte so, wie sie sind, und verteilen sie in großem Umfang weiter.

Ein Dokument mit kaputten Links und veralteten Übersetzungen, das noch drei Wochen bis zur Prüfung hat, kann in diesen drei Wochen viel Schaden anrichten, vor allem, wenn ein KI-Assistent darauf basierend vertrauensvoll Antworten liefert.

**Verfallsdaten sind das Minimum an praktikablem Ansatz für die Dokumentationskontrolle. Wenn die Dokumentation von Systemen konsumiert wird, die nicht selbst denken können, brauchst du eine Freshness-Bewertung.

Erste Schritte

Wenn du deine Dokumente bereits mit einem Verfallsdatum versiehst (gut für dich, denn die meisten Teams tun das nicht), kannst du die Freshness-Bewertung folgendermaßen einführen:

Beginne mit der Verfolgung von Links. Überprüfe deine 50 wichtigsten Dokumente auf defekte Links. Die Zahl wird dich wahrscheinlich überraschen.
Prüfe das Alignment der Übersetzungen. Wenn du mehrsprachige Dokumente hast, vergleiche das Datum der letzten Änderung zwischen dem Quelltext und den Übersetzungen. Wie viele sind mehr als einen Monat im Rückstand?
Überprüfe die Leserschaft. Welche Dokumente werden überhaupt nicht gelesen? Werden sie noch gebraucht, oder sollten sie archiviert werden?
Sprecht mit eurem KI-Team. Wenn ihr einen internen KI-Assistenten habt, fragt ihn, welche Dokumente er abruft. Überprüfe dann die Aktualität dieser Dokumente.

Du wirst wahrscheinlich feststellen, dass deine technisch nicht abgelaufenen Dokumente eine Menge Probleme haben, die das Verfallsdatum nie aufdecken wird.

Das Verfallsdatum verrät dir, ob jemand ein Dokument kürzlich geprüft hat. Die Frische sagt dir, ob das Dokument im Moment tatsächlich gesund ist. Das eine ist ein Kalenderereignis. Das andere ist ein lebendes Signal.

Du brauchst beides. Aber wenn du nur Verfallsdaten hast, fliegst du zwischen den Kontrollpunkten im Blindflug.

Ein Dokument wird nicht an seinem Überprüfungsdatum ungültig. Es veraltet in dem Moment, in dem sich etwas ändert und niemand es bemerkt. Die Frischebewertung merkt es.

Rasepi kombiniert verbindliche Verfallsdaten mit einer kontinuierlichen Frischeüberwachung. Jedes Dokument erhält oder verliert seinen Vertrauenswert in Echtzeit. Kein Warten, keine blinden Flecken, keine Überraschungen bei der Überprüfung.

So funktioniert die Frischebewertung →

*Dies ist Teil 2 einer zweiteiligen Serie. Wenn du sie noch nicht gelesen hast, beginne mit Teil 1: Die Kennzahl, die dein Team nicht verfolgt.

Content Freshness, Teil 1: Die Kennzahl, die dein Team nicht im Blick hat

2026-03-16T00:00:00Z

Es gibt einen Moment, den jedes Entwicklungsteam schon einmal erlebt hat. Jemand findet ein Dokument im internen Wiki, folgt den Anweisungen und dann geht etwas kaputt. Sie schicken eine Nachricht an den Channel: "Stimmt das noch?" Niemand weiß es. Die Person, die es geschrieben hat, ist vor acht Monaten gegangen. Im Dokument steht, dass es zuletzt 2024 bearbeitet wurde.

Das ist das Problem mit der Aktualität. Und es wird immer schlimmer.

Der alte Vertrag bricht zusammen

Lange Zeit hatten Dokumentationen einen impliziten Vertrag: Jemand schreibt sie, alle vertrauen darauf, und gelegentlich aktualisiert sie jemand. Vielleicht. Dieser Vertrag funktionierte gerade noch, als die Dokumentation nur von Leuten konsumiert wurde, die sich ein Urteil bilden konnten. Wenn eine Einrichtungsanleitung nicht ganz stimmte, passte ein erfahrener Ingenieur sie einfach im Handumdrehen an.

Aber diese Welt ist vorbei. Heute wird deine Dokumentation nicht nur von Menschen gelesen. Sie wird von KI-Tools, internen Chatbots, Onboarding-Automatisierung und Suchsystemen genutzt, die jedes Wort als gleichwertige Wahrheit behandeln. Ein KI-Assistent blinzelt nicht auf eine Dokumentation und denkt: "Das sieht ein bisschen veraltet aus", sondern er liest den Text, verarbeitet ihn als Tatsache und serviert ihn mit vollem Vertrauen.

Veraltete Dokumente plus KI gleich vertrauenswürdige falsche Antworten in großem Umfang.

Was Frische wirklich bedeutet

Frische bedeutet nicht nur "wann wurde das zuletzt bearbeitet". Eine Dokumentation kann gestern bearbeitet worden sein und trotzdem auf eine veraltete API verweisen. Echte Frische ist ein zusammengesetztes Signal:

Review-Status. Hat jemand explizit bestätigt, dass das Dokument noch aktuell ist?
Link-Gesundheit. Werden die URLs in der Dokumentation noch aufgelöst?
Leserschaft. Nutzt das überhaupt noch jemand, oder wurde es aufgegeben?
Kontextabweichung. Haben sich verwandte Dokumente geändert, während dieses Dokument gleich geblieben ist?
Übersetzungsabgleich. Wenn das Dokument in fünf Sprachen existiert, sind dann alle auf dem neuesten Stand?
Gemeinschaftssignale. Haben Leser dieses Dokument als veraltet gekennzeichnet?

Jede dieser Angaben sagt dir etwas anderes. Zusammen ergeben sie einen Trust Score: eine einzelne Zahl, die angibt, wie viel Vertrauen du in einen Inhalt setzen solltest.

Warum das gerade jetzt wichtig ist.

Drei Dinge sind zusammengekommen, um die Aktualität von Inhalten dringend erforderlich zu machen:

1. KI verbraucht deine Wissensbasis

Ganz gleich, ob du ein internes RAG-System einsetzt, Copilot in deiner IDE verwendest oder einen KI-Assistenten mit der Beantwortung von Fragen aus deinen Dokumenten beauftragst: Die Qualität des Quellmaterials bestimmt direkt die Qualität der Ausgabe. Garbage in, garbage out war noch nie so wörtlich zu nehmen.

Wenn ein Entwickler deinen KI-Assistenten fragt: "Wie kann ich in Staging deployen?" und er antwortet mit einem zwei Jahre alten Runbook, das auf eine Infrastruktur verweist, die du inzwischen migriert hast, dann ist das nicht nur eine falsche Antwort. Es ist das verlorene Vertrauen in das gesamte System.

2. Teams sind verteilter denn je

Ein Team in Berlin, ein anderes in São Paulo, ein drittes in Tokio. Alle lesen die gleiche Dokumentation, oft in verschiedenen Sprachen. Wenn der englische Quelltext veraltet, werden auch alle darauf aufbauenden Übersetzungen veraltet, aber niemand merkt es, weil die Übersetzungen, wenn überhaupt, separat gepflegt werden.

3. Der Druck durch Compliance und Audits steigt

Regulierte Branchen beginnen zu fragen: "Kannst du beweisen, dass diese Dokumentation zu dem Zeitpunkt, als sie referenziert wurde, aktuell war?" Wenn deine Antwort lautet: "Na ja, irgendjemand hat sie wahrscheinlich überprüft", wird das nicht ausreichen.

So sieht ein Freshness-First-Ansatz aus

Der Grundgedanke ist einfach: Jedes Dokument muss sich kontinuierlich das Recht verdienen, vertrauenswürdig zu sein.

Das bedeutet:

Vorgeschriebene Überprüfungsdaten. Jedes Dokument bekommt ein Verfallsdatum, wenn es erstellt wird. Keine Ausnahmen. Wenn das Datum erreicht ist, wird der Eigentümer benachrichtigt und das Dokument wird markiert, bis es jemand explizit wieder freigibt.
Automatische Gesundheitsüberwachung Im Hintergrund prüft das System kontinuierlich auf defekte Links, Lesertrends und kontextuelle Veränderungen. Diese Signale fließen in eine Live-Bewertung ein, die aktualisiert wird, ohne dass jemand etwas tun muss.
Die Aktualität wirkt sich auf die Sichtbarkeit aus. Dies ist der Schlüsselmechanismus. Ein Dokument mit hoher Punktzahl taucht in den Suchergebnissen ganz oben auf und kann als Quelle für KI-Antworten verwendet werden. Ein Dokument mit einer niedrigen Punktzahl fällt in der Rangliste zurück. Fällt es unter einen Schwellenwert, wird es ganz von den KI-Antworten ausgeschlossen.
Transparenz. Jeder kann sehen, warum ein Dokument so bewertet wurde, wie es bewertet wurde. Kaputte Links, überfällige Überprüfungen, geringe Leserschaft - die Signale sind sichtbar und nicht in einem Backend-Bericht versteckt, den niemand liest.

Die Kosten des Nichtstuns

So sieht es aus, wenn du die Aktualität nicht verfolgst:

Neue Mitarbeiter folgen veralteten Onboarding-Dokumenten und verbringen ihre erste Woche verwirrt
KI-Tools liefern falsche Antworten und niemand versteht, warum.
Compliance-Dokumente werden stillschweigend veraltet und stellen ein Audit-Risiko dar.
Übersetzungen geraten aus dem Gleichgewicht und Teams in verschiedenen Regionen arbeiten mit unterschiedlichen Versionen der Realität
Ingenieure vertrauen dem Wiki nicht mehr und greifen auf Slack-Nachrichten zurück, wodurch ein eigenes Wissenssilo entsteht

Die Kosten, die durch veraltete Dokumentation entstehen, sind enorm, aber sie sind unsichtbar, bis etwas kaputt geht.

Ein praktischer Ansatzpunkt

Du musst nicht alles auf einmal überarbeiten. Fang mit diesen Punkten an:

Überprüfe deine 20 meistgelesenen Dokumente. Wann wurden sie zuletzt überprüft? Sind die Links noch gültig? Ist der Inhalt noch korrekt?
Setz dir Überprüfungsdaten. Auch wenn du sonst nichts tust, schafft die Angabe eines "Überprüfungsdatums" auf jedem Dokument Verantwortlichkeit.
Verfolge, was deine KI-Tools beschaffen. Wenn du einen internen KI-Assistenten hast, schau dir an, welche Dokumente er abruft. Sind diese Dokumente aktuell?
Mach die Aktualität sichtbar. Platziere den Wert dort, wo er sichtbar ist: neben dem Titel des Dokuments, in den Suchergebnissen, in der Seitenleiste. Sichtbarkeit schafft Druck, die Aktualität zu erhalten.

Dokumentationsfrische ist kein Feature. Es ist ein grundlegender Wandel in der Art und Weise, wie wir über organisatorisches Wissen denken. In einer Welt, in der KI-Tools deine Dokumente in großem Umfang verbrauchen und weiterverteilen, stellt sich nicht mehr die Frage, ob du es dir leisten kannst, auf Aktualität zu achten. Es geht darum, ob du es dir leisten kannst, es nicht zu tun.

Jedes Dokument sollte beweisen müssen, dass es noch vertrauenswürdig ist. Nicht nur einmal. Kontinuierlich.

Das ist es, was wir bei Rasepi aufbauen. Eine Plattform, bei der Frische kein nachträglicher Gedanke ist. Sie ist das Fundament, auf dem alles andere aufgebaut ist. Review Enforcement, Live Health Scoring, eine nach Frische gewichtete Suche und KI-Antworten, die nur Quellen verwenden, denen du vertrauen kannst.

So funktioniert's →

Dies ist Teil 1 einer zweiteiligen Serie. In Teil 2: Jenseits des Verfallsdatums untersuchen wir, wie die kontinuierliche Frischeüberwachung die Lücken füllt, die das Verfallsdatum offen lässt.

Bringe deiner KI bei, veraltete Dokumentation zu ignorieren

2026-03-12T00:00:00Z

So sieht es aus, wenn du einen KI-Assistenten auf deiner internen Wissensdatenbank einsetzt:

Ein neuer Ingenieur fragt: "Wie richte ich die Staging-Umgebung ein?"

Die KI durchsucht deine Dokumentation, findet drei relevante Dokumente, stellt eine Antwort zusammen und präsentiert sie mit Zuversicht. Der Techniker folgt den Anweisungen. Die ersten beiden Schritte funktionieren. Schritt drei verweist auf ein CLI-Tool, das seit sechs Monaten nicht mehr verwendet wird. Schritt vier beschreibt ein Infrastruktur-Setup, das während einer Migration ersetzt wurde, die niemand dokumentiert hat.

Der Techniker kommt nicht weiter. Er wendet sich an den Teamkanal. Jemand sagt: "Oh, diese Dokumentation ist wirklich alt." Die KI hat das nicht gewusst. Sie kann es auch nicht wissen. Sie hat einfach alles geholt, was sie gefunden hat, und es als Wahrheit dargestellt.

**Das ist das Standardverhalten jedes RAG-Systems, jedes KI-Suchwerkzeugs und jedes LLM-gestützten Assistenten, den du jemals für interne Dokumente benutzt hast. Sie holen sich alles. Sie machen keinen Unterschied. Sie können nicht zwischen frisch und alt unterscheiden.

Und sie zerstören das Vertrauen in KI-Tools schneller, als diese Tools es aufbauen können.

Warum KI-Assistenten blind für Qualität sind

Große Sprachmodelle und Retrieval-Augmented-Generating-Systeme (RAG) suchen nach Text, der für eine Anfrage semantisch relevant ist, und verwenden diesen Text dann, um eine Antwort zu generieren. Der Relevanzabgleich ist in der Regel hervorragend. Vektorsuche und Einbettungen sind wirklich gut darin, Inhalte zu finden, die sich auf eine Frage beziehen.

Aber Relevanz ist nicht dasselbe wie Zuverlässigkeit.

Ein Dokument, das im Jahr 2023 über deinen Kubernetes-Bereitstellungsprozess geschrieben wurde, ist für die Frage "Wie führe ich eine Produktionsbereitstellung durch?" höchst relevant. Es ist aber auch völlig falsch, wenn du im Jahr 2024 auf eine andere Plattform migriert hast. Die KI sieht relevanten Text. Sie sieht kein Dokument, das 18 Monate veraltet ist, kaputte Links enthält und von niemandem gelesen wird.

Die meisten KI-Systeme haben genau ein Ranking-Signal: semantische Ähnlichkeit mit der Suchanfrage. Das war's. Sie prüfen nicht:

Wann wurde dieses Dokument zuletzt überprüft?
Sind die Links darin noch gültig?
Liest dieses Dokument überhaupt noch jemand?
Wurde der Inhalt von Lesern als veraltet gekennzeichnet?
Handelt es sich um einen Entwurf, eine archivierte Seite oder ein aktuelles Dokument?
Wenn das Dokument in mehreren Sprachen vorliegt, sind die Übersetzungen aktuell?

Ohne diese Signale führt die KI den Schlüsselwortabgleich mit zusätzlichen Schritten durch. Das ist zwar beeindruckend, aber im Grunde genommen nicht in der Lage, dir zu sagen, ob die Antwort, die sie dir gibt, auf Inhalten basiert, denen du vertrauen kannst.

Das Vertrauensproblem

Das wäre nicht so gefährlich, wenn KI-Tools unsichere Antworten mit entsprechenden Vorbehalten versehen würden. Das tun sie aber nicht. So funktionieren LLMs nicht. Sie generieren flüssige, vertrauenswürdige Texte, unabhängig davon, ob das Quellenmaterial aktuell oder alt ist.

Einem Menschen, der einen Wiki-Artikel liest, könnte auffallen, dass er veraltet aussieht. Das Seitenlayout ist veraltet. Die Screenshots zeigen eine Benutzeroberfläche, die es nicht mehr gibt. Am Ende steht ein Kommentar, der besagt: "Das ist veraltet". Ein Mensch kann ein Urteil fällen.

Eine KI kann das nicht. Sie liest den Text, verarbeitet ihn als gleichwertig mit jedem anderen Text und gibt eine Antwort, die verbindlich klingt. Der Nutzer, vor allem ein neuer Mitarbeiter, der nicht weiß, wie der aktuelle Prozess aussieht, hat keinen Grund, daran zu zweifeln.

Je selbstsicherer die KI klingt, desto mehr Schaden richtet veraltetes Ausgangsmaterial an.

Was die KI wirklich braucht

Damit ein KI-Assistent vertrauenswürdige Antworten aus deiner Wissensdatenbank geben kann, braucht er mehr als Text und Einbettungen. Er braucht Metadaten, die ihm sagen, welche Dokumente es wert sind, als Quellen verwendet zu werden. Konkret bedeutet dies:

1. Freshness Score

Ein numerisches Signal, das angibt, wie gesund ein Dokument im Moment ist. Nicht, wann es zuletzt bearbeitet wurde, das ist nur eine Angabe. Ein echter Freshness-Score kombiniert den Status der Rezensionen, den Zustand der Links, die Leserschaft, das Alignment der Übersetzung und die kontextuelle Abweichung in einer einzigen Zahl.

Wenn ein Dokument über einem Schwellenwert (z. B. 70 von 100) liegt, kann es als Quelle für KI-Antworten verwendet werden. Liegt es unter diesem Schwellenwert, wird es ausgeschlossen. Keine Ausnahmen.

Dieser einzige Mechanismus eliminiert die gefährlichste Klasse von KI-Fehlern: mit Sicherheit falsche Antworten, die auf veralteten Quellen basieren.

2. Verfallsstatus

Befindet sich das Dokument noch innerhalb des Prüfungszeitraums oder ist es bereits abgelaufen, ohne dass es neu genehmigt wurde? Ein abgelaufenes Dokument sollte stark depriorisiert oder ganz ausgeschlossen werden, unabhängig davon, wie relevant sein Inhalt für die Abfrage sein mag.

In Rasepi werden abgelaufene Dokumente markiert und ihre Frischebewertung sinkt automatisch. Ein KI-System, das die Wissensdatenbank abfragt, kann diesen Status sehen und entsprechend handeln.

3. Klassifizierungskennzeichen

Nicht jedes Dokument dient dem gleichen Zweck. Ein Entwurf sollte nicht als Quelle verwendet werden. Ein archiviertes Dokument sollte nicht in KI-Antworten auftauchen. Ein rein internes Dokument sollte nicht in Abfragen von externen Tools auftauchen.

Klassifizierungskennzeichen geben der KI Aufschluss darüber, um welche Art von Dokument es sich handelt:

Veröffentlicht. Aktuell, genehmigt, sicher zu verwenden
Entwurf. In Arbeit, sollte nicht zitiert werden
Unter Review. Verfall ausgelöst, wartet auf erneute Genehmigung
Archiviert. Nicht mehr aktiv, nur als Referenz aufbewahrt
Intern / Extern. Kontrolliert den Sichtbarkeitsbereich

Wenn ein KI-Assistent eine Anfrage bearbeitet, kann er nach der Klassifizierung filtern, bevor er die Relevanz des Inhalts prüft. Ein Entwurfsdokument, das perfekt auf die Anfrage passt, sollte nie als Antwort angezeigt werden.

4. Signale auf Sprachebene

Wenn deine Wissensdatenbank mehrsprachig ist, muss die KI wissen, ob die Version, die sie abruft, aktuell ist. Eine französische Übersetzung, die drei Monate hinter dem englischen Original zurückliegt, ist zwar technisch gesehen auf Französisch relevant, aber die Informationen könnten veraltet sein.

Rasepi prüft die Aktualität auf der Ebene der einzelnen Sprachen. Jede Übersetzung hat ihre eigene Punktzahl, die darauf basiert, ob sich die Quellblöcke seit der letzten Aktualisierung der Übersetzung geändert haben. Eine KI, die die französische Wissensdatenbank abfragt, kann erkennen, dass die französische Version eines Dokuments veraltet ist und entweder:

auf die englische Quelle zurückgreifen (die aktuell ist)
eine Warnung einfügen, dass die französische Version veraltet sein könnte
das Dokument ganz ausschließen

5. Leser-Signale

Wenn mehrere Leser ein Dokument als veraltet markiert haben, sollte dieses Signal die Gewichtung des Dokuments in den KI-Antworten verringern. Crowdsourced-Qualitätssignale sind zwar verrauscht, aber sie sind wertvoll, vor allem wenn sie mit anderen Aktualitätskennzahlen kombiniert werden.

Wie funktioniert das in der Praxis?

Schauen wir uns an, was passiert, wenn ein KI-Assistent eine Rasepi-Wissensdatenbank abfragt:

Abfrage: "Wie gehen wir mit einem P1-Vorfall um 2 Uhr morgens um?"

Schritt 1: Retrieval mit Filterung. Das System sucht nach semantisch relevanten Dokumenten. Bevor es ein Ranking erstellt, filtert es aus:

Dokumente mit einem Freshness Score unter dem Schwellenwert
Abgelaufene Dokumente, die nicht wieder freigegeben wurden
Entwürfe und archivierte Inhalte
Dokumente, deren Sprachversion veraltet ist (wenn die Abfrage in einer Nicht-Primärsprache erfolgt)

Schritt 2: Freshness-gewichtetes Ranking. Unter den verbleibenden Dokumenten werden die Dokumente mit höheren Freshness-Werten höher eingestuft. Ein Dokument mit 94 Punkten ist einem Dokument mit 72 Punkten überlegen, auch wenn das Dokument mit 72 Punkten eine etwas höhere semantische Ähnlichkeit aufweist.

Schritt 3: Generierung von Antworten. Die KI generiert eine Antwort aus den gefilterten, nach Freshness bewerteten Quellen. Jede Quelle wird mit ihrem Freshness-Score zitiert.

Schritt 4: Staleness-Warnungen. Wenn die beste verfügbare Quelle einen grenzwertigen Freshness-Wert hat, fügt die KI einen Warnhinweis ein: "Hinweis: Die Hauptquelle für diese Antwort wurde zuletzt vor 60 Tagen überprüft. Das solltest du mit dem Team abklären."

Vergleiche das mit dem Standardverhalten: Relevanten Text finden, vertrauenswürdige Antwort generieren und auf das Beste hoffen.

Was passiert, wenn du das nicht tust

Die Folgen von KI-Systemen, die auf ungefilterten Wissensdatenbanken arbeiten, sind vorhersehbar und teuer:

Verwirrung bei Neueinstellungen Der häufigste Anwendungsfall von KI für interne Dokumente ist das Onboarding. Neue Mitarbeiter wissen naturgemäß nicht, was aktuell ist und was veraltet ist. Sie vertrauen der KI. Die KI traut allem. Veraltete Dokumente werden vertrauensvoll zugestellt.

**Wenn dein KI-Assistent Anleitungen zu regulatorischen Prozessen gibt und dabei auf veraltete Dokumente zurückgreift, könnte der Rat nicht nur falsch sein, sondern auch nicht den Vorschriften entsprechen. "Die KI hat mir gesagt, dass ich das tun soll" ist bei einem Audit nicht haltbar.

Vertrauensverlust. Jedes Mal, wenn die KI eine falsche Antwort gibt, sinkt das Vertrauen der Nutzer/innen in sie. Nach drei oder vier schlechten Erfahrungen hören sie auf, sie zu benutzen. Die Investition in KI-Werkzeuge bringt keinen Nutzen, weil die zugrunde liegenden Inhalte nicht vertrauenswürdig sind.

Schattenwissen. Wenn die Menschen das Vertrauen in die offizielle Wissensbasis (und die darauf aufbauende KI) verlieren, schaffen sie sich ihr eigenes: Slack-Nachrichten, persönliche Notizen, Stammeswissen, das in Meetings geteilt wird. Die Fragmentierung, die das Wiki eigentlich verhindern sollte, findet trotzdem statt, nur anders.

Die Lösung liegt an der Quelle, nicht am Modell

Die Versuchung ist groß, dieses Problem auf der KI-Ebene zu lösen: bessere Prompts, ausgefeiltere RAG-Pipelines, fein abgestimmte Modelle, die allein anhand des Textes erkennen können, ob etwas veraltet ist. Das ist der falsche Ansatz.

Die Lösung liegt an der Quelle. Wenn deine Dokumente reichhaltige, genaue Metadaten über ihren aktuellen Zustand enthalten (Frischegrad, Verfallsstatus, Klassifizierung, Sprachausrichtung, Lesersignale), kann jedes KI-System diese Metadaten nutzen, um bessere Entscheidungen zu treffen. Du brauchst kein schlaueres Modell. Du brauchst intelligentere Dokumente.

Das ist es, was Rasepi bietet:

Jedes Dokument hat einen Live-Frische-Score, der ständig auf der Grundlage von Linkstatus, Leserschaft, Überprüfungsstatus und mehr aktualisiert wird.
Jedes Dokument hat ein Verfallsdatum**, das eine Überprüfung auslöst, wenn es eintrifft.
Jedes Dokument hat eine Klassifizierung** (veröffentlicht, Entwurf, in Prüfung, archiviert)
Jede Sprachversion hat ihr eigenes Aktualitätssignal**, so dass veraltete Übersetzungen unabhängig voneinander erkannt werden.
Leserkennzeichen und Querverweisverfolgung** liefern zusätzliche Qualitätssignale

Wenn ein KI-System die Wissensdatenbank von Rasepi abfragt, sind all diese Metadaten verfügbar. Die KI muss nicht raten, ob ein Dokument vertrauenswürdig ist. Das Dokument sagt es ihr.

Ein praktischer Ausgangspunkt

Wenn du heute einen KI-Assistenten auf deiner Wissensdatenbank laufen hast, kannst du innerhalb von 30 Minuten damit beginnen, das Problem zu bewerten:

Stelle deinem KI-Assistenten 10 Fragen, auf die du die Antworten kennst. Notiere, welche Antworten veraltete Quellen verwenden. Du wirst wahrscheinlich feststellen, dass mindestens 2-3 von 10 auf veralteten Inhalten basieren.
Überprüfe die Quelldokumente. Sieh dir für jede Antwort, die die KI gegeben hat, das Quelldokument an. Wann wurde es zuletzt überprüft? Sind die Links gültig? Würdest du dem Dokument vertrauen, wenn du es selbst lesen würdest?
Suche nach dem schlimmsten Fall. Finde dein ältestes, am meisten vernachlässigtes Dokument, das immer noch in den Suchergebnissen erscheint. Stelle der KI eine Frage, die es zum Vorschein bringen würde. Verwendet die KI es? Mit ziemlicher Sicherheit tut sie das.
Schätze die Auswirkungen ab. Wie viele Anfragen bearbeitet dein KI-Assistent pro Tag? Wenn 20-30% der Antworten auf veralteten Inhalten beruhen, wie hoch sind dann die Kosten in Form von verschwendeter Zeit, falschen Entscheidungen und verlorenem Vertrauen?

KI-Assistenten sind nur so gut wie die Inhalte, auf denen sie aufbauen. Momentan behandeln die meisten von ihnen jedes Dokument in deiner Wissensdatenbank als gleichwertig. Sie holen sich alles, das Dokument, das gestern geprüft wurde, und das, das seit zwei Jahren niemand mehr angefasst hat, und präsentieren es mit dem gleichen Vertrauen.

Das ist kein Modellproblem. Es ist ein Problem der Datenqualität. Und die Lösung ist ganz einfach: Gib deinen Dokumenten Metadaten, die den KI-Tools sagen, worauf sie vertrauen sollen.

Dein KI-Assistent sollte nicht zuversichtlich klingen, wenn er eine Antwort aus einem Dokument erhält, das niemand in den letzten 18 Monaten überprüft hat. Mit den richtigen Signalen wird er das nicht tun.

Mit Rasepi erhält jedes Dokument seinen eigenen Vertrauenswert: Frische, Verfallsstatus, Klassifizierung, Sprachausrichtung. KI-Tools fragen die Wissensbasis ab und erhalten nicht nur den Inhalt, sondern auch den Kontext. Vertrauenswürdige Quellen tauchen auf. Veraltete Quellen nicht. So sollte eine KI-gestützte Dokumentation funktionieren.

Schau, wie Rasepi mit KI-Tools funktioniert →

Es ist besser, mit Dokumenten zu sprechen, als sie zu lesen

2026-03-10T00:00:00Z

Es gibt einen Grund, warum die Leute sagen: "Lass uns darüber reden", wenn etwas komplex ist.

Wenn wir versuchen, eine neue Idee zu verstehen, ein Problem zu lösen oder uns unter Druck an einen Prozess zu erinnern, ist ein Gespräch oft einfacher als Lesen. Nicht, weil Lesen schlecht ist. Lesen ist eines der mächtigsten Werkzeuge, die der Mensch je entwickelt hat. Aber Lesen ist eine erlernte Fähigkeit, die auf etwas viel Älterem aufbaut: dem Sprechen.

Wir sprechen, lange bevor wir lesen.

Das ist wichtiger, als man denkt, vor allem jetzt, wo ein Großteil des weltweiten Wissens in Dokumenten, Wikis, PDFs und langen internen Seiten steckt, die niemand öffnen will, wenn er nicht unbedingt muss.

Lesen wird gelernt. Konversation ist angeboren.

Die Menschen haben sehr lange gesprochen, bevor sie etwas aufgeschrieben haben. Kinder lernen auf natürliche Weise, gesprochene Sprache zu verstehen. Zum Lesen braucht man ausdrückliche Anweisungen, Wiederholungen und jahrelange Übung.

Selbst für sehr gebildete Erwachsene ist Lesen immer noch ein bewussterer Akt als Zuhören oder Sprechen. Es erfordert visuelle Konzentration, kontinuierliche Aufmerksamkeit, ein Arbeitsgedächtnis und die Interpretation von Strukturen auf der Seite. Du entschlüsselst Symbole, zerlegst Sätze, stellst Zusammenhänge her und entscheidest, was wichtig ist.

Konversation funktioniert anders. Wenn Informationen in gesprochener, interaktiver Form übermittelt werden, macht das Gehirn eine andere Erfahrung:

Es fühlt sich sequentiell und nicht visuell überwältigend an
Es gibt sofortiges Feedback und Klarheit
Es reduziert die Notwendigkeit, große Textblöcke zu scannen und zu filtern
Es spiegelt die Art und Weise wider, wie Menschen bereits im echten Leben um Hilfe bitten

Dieser letzte Punkt ist sehr wichtig. Unter Unsicherheit wollen die meisten Menschen nicht instinktiv 1.500 Wörter lesen. Sie wollen fragen: "Was mache ich als Nächstes?"

Reden senkt die kognitive Reibung

Ein Dokument ist statisch. Es enthält alles auf einmal.

Das klingt nützlich, und oft ist es das auch. Aber es schafft auch Reibung. Eine Seite voller Überschriften, Aufrufe, Links, Notizen, Beispiele und Sonderfälle zwingt den Leser zu entscheiden, was er ignorieren soll. Das ist kognitiv teuer.

Wenn du mit einem Informationssystem sprichst, machst du in der Regel die gegenteilige Erfahrung: Erst die Relevanz, dann die Details.

Du stellst eine Frage. Du bekommst eine Antwort. Dann stellst du eine Folgefrage.

Dieses Interaktionsmuster reduziert den mentalen Aufwand auf mehrere wichtige Arten:

1. Es grenzt den Problemraum ein

Ein vollständiges Dokument zeigt die gesamte Landschaft. Ein Gespräch zeigt den nächsten nützlichen Schritt.

Wenn jemand fragt: "Wie bringe ich einen neuen Ingenieur an Bord?" will er in der Regel nicht gleich das ganze Handbuch. Sie wollen eine Orientierung. Mit einem Gespräch können sie klein anfangen und nur bei Bedarf erweitern.

2. Es schont das Arbeitsgedächtnis

Beim Lesen musst du mehrere Dinge im Kopf behalten, während du nach der relevanten Stelle suchst. Gesprochene oder konversationelle Interaktion macht diese Anstrengung überflüssig. Das System übernimmt einen Großteil des Filterns für dich.

3. Es fühlt sich sozial vertraut an

Wir Menschen sind an den gegenseitigen Austausch gewöhnt. Wir fragen. Jemand antwortet. Wir verfeinern. Sie klären. Diese Schleife ist eine der ältesten Formen des Lernens, die wir kennen.

Selbst wenn der "Jemand" ein System ist, fühlt sich die Struktur immer noch natürlich an.

Lesen ist nicht passiv. Das ist genau der Punkt.

Ein Grund, warum sich Reden leichter anfühlen kann, ist, dass Lesen nicht so mühelos ist, wie die Leute annehmen. Geübte Leser/innen lassen es mühelos aussehen, aber der Prozess ist sehr aktiv.

Um gut zu lesen, musst du das tun:

eine Struktur erkennen
auf die Bedeutung schließen
Zweideutigkeiten auflösen
den Kontext im Gedächtnis behalten
einen Abschnitt mit einem anderen zu verbinden
entscheiden, wann man überfliegt und wann man langsamer wird

Das ist echte kognitive Arbeit.

In vielen Situationen lohnt sich diese Arbeit. Tiefgehendes Lesen hilft bei Nuancen, Präzision und langfristigem Verständnis. Aber in anderen Situationen, vor allem wenn jemand müde, gestresst oder überlastet ist oder einfach nur versucht, sich zu befreien, ist Reden oft die geistig leichtere Option.

Das gilt besonders am Arbeitsplatz, wo die Menschen normalerweise nicht unter idealen Bedingungen an die Dokumentation herangehen. Sie sind es:

mitten in der Arbeit
unterbrochen
im Kontext wechselnd
versuchen, etwas schnell zu lösen
oft schon leicht frustriert

In diesem Zustand kann sich der konversationelle Zugang zu Informationen dramatisch besser anfühlen als der Zugriff auf eine Seite.

Sprechen verändert die Beziehung zu Informationen

Es gibt hier auch eine emotionale Dimension.

Dokumente können sich formell und distanziert anfühlen. Sie implizieren: Lies das alles, verstehe es richtig und übersehe nichts Wichtiges. Das kann als Nachschlagewerk nützlich sein, aber es kann auch zum Zögern anregen.

Konversation fühlt sich freizügig an. Du kannst vage sein. Du kannst schlecht fragen. Du kannst Verwirrung zugeben. Du kannst sagen: "Ich weiß nicht wirklich, wonach ich suche, aber ich brauche die Sache mit den Zugangsanfragen."

Das ist wichtig, denn die Leute meiden Unterlagen oft nicht, weil sie Informationen nicht mögen, sondern weil sie den Aufwand und die Ungewissheit scheuen, die damit verbunden sind, den richtigen Teil der Unterlagen zu finden.

Reden baut diese Barriere ab.

Warum das jetzt wichtig ist

Lange Zeit mussten Dokumente gelesen werden, weil es keine praktische Alternative gab. Die Suche erleichterte das Auffinden von Seiten, aber sie änderte das Interaktionsmodell nicht. Du musstest die Seite immer noch öffnen, sie einscannen und das herausziehen, was du brauchst.

Das ändert sich jetzt.

Da die Benutzeroberflächen immer dialogorientierter werden, erwarten die Menschen zunehmend, dass sie auf Informationen reagieren, anstatt einfach nur zu existieren. Sie wollen in einfacher Sprache nach dem fragen, was sie brauchen, und etwas erhalten, das auf den jeweiligen Moment zugeschnitten ist.

Das macht das Lesen nicht überflüssig. Es verändert nur seine Rolle.

Das Lesen wird zur Tiefenschicht. Die Konversation wird zur Zugangsebene.

Die besten Systeme werden beides unterstützen:

Sprechen, wenn du Orientierung oder Geschwindigkeit brauchst
Lesen, wenn du Tiefe, Überprüfung oder vollen Kontext brauchst

Das Risiko einer zu starken Vereinfachung

Es gibt einen wichtigen Vorbehalt: Mit Informationen zu sprechen fühlt sich nur dann besser an, wenn die Antworten zuverlässig sind.

Wenn eine Dialogschnittstelle nur unvollständige, irreführende oder zu selbstsichere Antworten gibt, ist das Erlebnis schlechter als das Lesen, weil es dem Nutzer die Möglichkeit nimmt, das Quellmaterial direkt zu prüfen.

Die Zukunft liegt also nicht darin, "alle Dokumente durch Sprache zu ersetzen". Die Zukunft liegt darin, den Menschen einen menschlicheren Zugang zu Dokumenten zu ermöglichen, ohne die Tiefe und Präzision zu verlieren, die schriftliches Wissen bietet.

Dieses Gleichgewicht ist wichtig. Gespräche sind einfacher, aber Dokumente haben immer noch die dauerhafte Struktur, die Details und die Verantwortlichkeit, die Organisationen brauchen.

Eine menschlichere Schnittstelle zum Wissen

Der tiefere Punkt ist einfach: Menschen denken nicht von Natur aus in Seiten. Sie denken in Fragen, Geschichten, Fragmenten und Dialogen.

Wir fragen:

Was bedeutet das?
Was muss ich zuerst tun?
Was ist das Wichtigste?
Kannst du das anders erklären?
Was hat sich geändert?

Das sind Gesprächsmanöver, keine Lesemanöver.

Wenn es sich also leichter anfühlt, mit Informationen zu sprechen als sie zu lesen, ist das kein Zeichen von Denkfaulheit. Es ist in der Regel ein Zeichen dafür, dass die Schnittstelle der Art und Weise entspricht, wie das Gehirn Ungewissheit am liebsten angeht.

Lesen bleibt wichtig. Aber als Einstieg in das Wissen fühlt sich das Gespräch oft besser an, weil es dem entspricht, was wir von Natur aus sind.

Wir sind nicht in erster Linie Leser. Wir sind in erster Linie Redner. Die intuitivsten Wissenssysteme werden sich das merken.

Dokumentationsplattformen für eine andere Ära

2026-03-08T00:00:00Z

Confluence und Notion sind keine schlechten Produkte. Das muss gleich zu Beginn klar gesagt werden.

Sie waren aus guten Gründen erfolgreich. Confluence wurde in vielen Unternehmen zur Standard-Heimat für interne Dokumentation, weil es Teams einen zentralen Ort zum Schreiben, Organisieren und Teilen von Wissen bot. Notion überzeugte durch seine Flexibilität, die übersichtlichere Schreibweise und eine modernere Produktoberfläche.

Beide Plattformen lösten echte Probleme in der Zeit, für die sie entwickelt wurden.

Das Problem ist nun, dass sich die Welt um sie herum schneller verändert hat als ihre Grundlagen.

Wir leben nicht mehr in einer Welt, in der Dokumentation nur geschrieben, gespeichert und durchsucht werden muss. Wir befinden uns in einer Welt, in der zunehmend erwartet wird, dass Dokumentation vorhanden ist:

maschinenlesbar
auf Aktualität bedacht
sicher für KI-Abfragen
strukturiert genug für die Automatisierung
dynamisch über Sprachen und Zielgruppen hinweg
kontinuierlich vertrauenswürdig, nicht nur verfügbar

Das ist eine andere Messlatte.

Sie wurden für ein Vor-AI-Modell des Wissens entwickelt.

Traditionelle Dokumentationsplattformen wurden auf der Grundlage einer einfachen Annahme entwickelt: Wenn die Seite existiert und durchsuchbar ist, ist das Problem weitgehend gelöst.

Das war gut genug, als der Hauptnutzer noch ein Mensch war, der ein Wiki öffnete, die Seite überflog und ein Urteil abgab. In diesem Modell bestand die Aufgabe der Plattform darin, das Verfassen und Navigieren zu erleichtern.

KI ändert die Aufgabenbeschreibung.

Jetzt speichert die Plattform nicht nur Wissen für Menschen. Sie produziert Quellenmaterial für Systeme, die das Wissen automatisch abrufen, einordnen, zusammenfassen und Fragen beantworten.

Das bringt neue Anforderungen mit sich, denen ältere Architekturen keine Priorität einräumten:

Welche Inhalte sind im Moment vertrauenswürdig?
Welche Seiten sind veraltet, aber noch durchsuchbar?
Welche Abschnitte wurden kürzlich geändert?
Welche Sprachversion ist aktuell?
Welcher Inhalt ist ein Entwurf, archiviert, regionsspezifisch oder wenig vertrauenswürdig?
Welche Dokumente sollten ganz von den KI-Antworten ausgeschlossen werden?

Eine Plattform, die nicht für diese Fragen entwickelt wurde, muss sie nachrüsten. Das ist immer schwieriger, als sie von Anfang an zu entwickeln.

Die Stärke des Erbes wird zum Nachteil des Erbes

Etablierte Produkte haben Vorteile: Vertrieb, Ökosystem, Marke, Vertrautheit mit den Kunden, Integrationen und Teams, die wissen, wie man liefert. Aber genau diese Stärken können den Strukturwandel verlangsamen.

Warum? Weil ausgereifte Plattformen Verpflichtungen mit sich bringen.

Sie haben:

jahrelang angesammelte Produktentscheidungen
eine große installierte Basis mit bestehenden Arbeitsabläufen
Erwartungen an die Abwärtskompatibilität
Plugins und Erweiterungen, die auf altem Verhalten basieren
Datenmodelle, die für die Anwendungsfälle von gestern optimiert sind

Wenn eine Plattform wie Confluence oder Notion eine wirklich neue Funktion hinzufügen will, muss sie diese Funktion oft um das bestehende System herum und nicht durch dieses hindurch integrieren.

Das ist die Herausforderung, die sich aus dem Bestehenden ergibt: Du baust nicht nur die Zukunft, sondern nimmst auch die Vergangenheit mit.

Das Hinzufügen von KI-Funktionen ist nicht das Gleiche wie KI-nativ zu werden.

Viele etablierte Plattformen legen jetzt KI oben drauf. Zusammenfassungen. Schreibhilfe. Verbesserte Suche. Q&A-Schnittstellen. Confluence verfügt über [Atlassian Intelligence] (https://www.atlassian.com/platform/intelligence), Notion über [Notion AI] (https://www.notion.com/product/ai) und GitBook über eine [KI-gestützte Suche] (https://docs.gitbook.com/product-tour/searching-your-content/gitbook-ai). Das sind nützliche Funktionen. Einige von ihnen sind gut.

Aber es gibt einen bedeutenden Unterschied zwischen:

dem Hinzufügen von KI-Funktionen zu einem Dokumentationsprodukt
der Entwicklung eines Dokumentationsprodukts, dessen Kernarchitektur von Anfang an auf KI ausgerichtet ist

Der erste Ansatz führt oft zu unterstützenden Funktionen am Rande. Der zweite Ansatz verändert die Grundlage.

Eine KI-native Wissensplattform stellt von Anfang an andere Designfragen:

Wie sollten Dokumente strukturiert sein, damit Systeme sicher auf sie zugreifen können?
Wie soll Vertrauen dargestellt werden?
Welche Metadaten müssen erstklassig und nicht optional sein?
Wie sollte die Sichtbarkeit veralteter Inhalte verringert werden?
Wie sollten Antworten eingeschränkt werden, wenn die zugrunde liegenden Quellen schwach sind?

Das sind architektonische Fragen, keine Funktionsfragen.

Frische Plattformen haben einen vorübergehenden Vorteil

Hier können neuere Plattformen gewinnen, zumindest für eine gewisse Zeit.

Eine neue Plattform hat die Freiheit, sich an den Zwängen von heute und nicht an den Gewohnheiten von gestern zu orientieren. Sie muss nicht ein Jahrzehnt an Annahmen darüber festhalten, was ein Dokument ist oder wie sich ein Wiki verhalten sollte. Sie kann frühzeitig andere Entscheidungen treffen:

Frische als ein Konzept erster Klasse behandeln
Quellensicherheit für Menschen und Maschinen sichtbar machen
umfangreichere Metadaten über den Zustand der Inhalte zu speichern
Mehrsprachige Workflows in das Kernmodell einbauen, anstatt sie aufzuschrauben
die Entscheidung, dass Suche und KI-Retrieval nach Vertrauen und nicht nur nach Relevanz bewertet werden sollten

Diese Freiheit ist wichtig.

In der Technologiebranche sind die etablierten Unternehmen oft in stabilen Zeiten am stärksten. Neue Marktteilnehmer sind oft am stärksten, wenn sich das Modell selbst verändert.

Die KI-Ära ist eine dieser Veränderungen.

Warum dies für Confluence besonders schwer ist

Confluence ist leistungsstark, aber es stammt aus einer älteren Weltanschauung. Es wurde um [Teambereiche, Seiten, hierarchische Navigation] (https://support.atlassian.com/confluence-cloud/docs/use-spaces-to-organize-your-work/) und ein [Plugin-reiches Unternehmensmodell] (https://marketplace.atlassian.com/) herum aufgebaut. Diese Entscheidungen waren sinnvoll. Für viele Organisationen sind sie immer noch sinnvoll.

Aber sie bedeuten auch, dass das Produkt eine Menge Komplexität mit sich bringt. Unternehmensplattformen können sich selten einfach neu erfinden. Sie müssen sich mit ihrer eigenen Geschichte auseinandersetzen.

Das macht die Modernisierung langsamer. Nicht unmöglich. Nur langsamer.

Wenn die Anforderungen der KI-Ära sauberere Metadaten, eine explizitere Vertrauensmodellierung oder eine stärker meinungsgeprägte Content Governance erfordern, kann ein System, das durch jahrelange Erweiterungen auf maximale Flexibilität ausgelegt ist, Schwierigkeiten haben, zusammenhängend zu funktionieren.

Warum dies für Notion besonders schwierig ist

Notion hat ein anderes Problem. Es fühlt sich neuer, leichter und flexibler an. Aber die Flexibilität kann auch gegen ihn arbeiten.

Die Stärke von Notion ist, dass [fast alles zu einer Seite, einer Datenbank, einer Notiz, einem leichtgewichtigen Dokument oder einem Raum für die Zusammenarbeit werden kann] (https://www.notion.com/product). Diese Flexibilität ist großartig für Teams. Weniger gut ist sie, wenn du starke Garantien darüber brauchst, was der Inhalt bedeutet, in welchem Zustand er sich befindet und ob er von einem KI-System als vertrauenswürdige Quelle verwendet werden sollte.

Je freier eine Plattform ist, desto schwieriger ist es, später eine verlässliche Semantik durchzusetzen.

KI-Systeme leben von Strukturen, expliziten Metadaten und Vertrauenssignalen. Flexible, universell einsetzbare Arbeitsbereiche benötigen oft viel Interpretation, bevor ihre Inhalte für diese Art der Nutzung sicher sind.

All das bedeutet nicht, dass sie dem Untergang geweiht sind.

Es wäre eine faule Analyse zu sagen, dass Confluence und Notion sich nicht anpassen können. Natürlich können sie das.

Sie haben kluge Teams, große Ressourcen und starke Anreize. Sie werden mehr KI-Funktionen anbieten. Sie werden die Abfrage, die Autorenunterstützung, die Zusammenfassungen, die Governance und die strukturierten Workflows verbessern. Mit der Zeit werden sie einen Großteil der Lücke schließen.

Aber das Timing ist wichtig.

Bei einem solchen Wandel ist oft derjenige im Vorteil, der am schnellsten neue Annahmen aufstellt. Neuere Plattformen können sich kohärenter bewegen, weil sie nicht so viel nachrüsten müssen. Das verschafft ihnen ein Zeitfenster.

Es ist vielleicht kein dauerhaftes Fenster. Aber es ist real.

Die nächste Phase der Dokumentationsplattformen

Die nächste Generation von Dokumentationswerkzeugen wird wahrscheinlich weniger danach beurteilt werden, wie gut sie Menschen Seiten schreiben lassen, sondern eher danach, wie gut sie Wissen als vertrauenswürdiges System verwalten.

Das bedeutet, dass die Gewinner wahrscheinlich fünf Dinge gut machen werden:

Sie werden Vertrauen explizit modellieren.
Sie unterscheiden aktuelles Wissen von veraltetem Wissen.
Sie behandeln die KI-Abfrage als eine zentrale Produktoberfläche, nicht als Zusatz.
Sie unterstützen mehrsprachiges und zielgruppenspezifisches Wissen ohne Fragmentierung.
Sie geben den Teams mehr Kontrolle darüber, welche Informationen für wen und unter welchen Bedingungen zugänglich sind.

Das ist eine andere Kategorie als das klassische Wiki.

Warum Neustarts wichtig sind

Es gibt Momente in der Softwarebranche, in denen ein neues Produkt einen Vorteil hat, nicht weil die etablierten Unternehmen inkompetent sind, sondern weil die Vergangenheit teuer ist.

Dies ist einer dieser Momente.

Eine neue Plattform kann vom ersten Tag an entscheiden, dass Dokumente nicht nur Seiten sind. Sie sind aktive Quellen für Menschen, Agenten, Suchsysteme und KI-Assistenten. Diese Annahme verändert alles, was danach kommt.

Confluence und Notion können diesen Weg gehen. Aber der Weg dorthin ist länger, weil sie Systeme umwandeln müssen, die für eine andere Ära optimiert waren.

Diese Umwandlung braucht Zeit. In der Zwischenzeit haben neuere Plattformen die Möglichkeit zu definieren, wie eine moderne Wissensinfrastruktur aussehen sollte.

Der größte Vorteil einer neuen Plattform ist nicht die Neuheit. Es ist die Freiheit von alten Annahmen, und zwar genau dann, wenn diese Annahmen nicht mehr funktionieren.

Dies ist ein perspektivischer Beitrag. Behauptungen über Konkurrenzprodukte basieren auf öffentlich zugänglichen Produktdokumentationen und Ankündigungen vom März 2026. Wir haben großen Respekt vor Confluence und Notion - sie sind hervorragende Produkte, die Millionen von Teams gute Dienste leisten.

Einblick in die Rasepi-Architektur: Plugins, Action Guards und Pipelines

2026-03-06T00:00:00Z

Die meisten Dokumentationsplattformen sprechen über "Erweiterbarkeit" wie Fluggesellschaften über "Beinfreiheit". Technisch vorhanden, praktisch enttäuschend. Ich wollte, dass die Architektur von Rasepi wirklich erweiterbar ist, ohne unvorhersehbar zu werden, also haben wir drei ineinander greifende Systeme entwickelt: Plugins für Fähigkeiten, Action Guards für die Kontrolle und Pipelines für die deterministische Ausführung.

In diesem Beitrag erfährst du, wie jedes dieser Systeme in unserer aktuellen Codebasis funktioniert.

Das Plugin-System: modular aufgebaut

Jedes Plugin in Rasepi implementiert IPluginModule, eine einzelne Schnittstelle, die erklärt, was das Plugin ist, welche Dienste es braucht und welche Routen es offenlegt:

public interface IPluginModule
{
    PluginManifest Manifest { get; }
    void RegisterServices(IServiceCollection services);
    void MapRoutes(IEndpointRouteBuilder routes);
}

Der PluginManifest ist ein reiner Datenblock. Er beschreibt das Plugin, ohne etwas auszuführen:

public sealed class PluginManifest
{
    public required string Id { get; init; }
    public required string Name { get; init; }
    public required string Version { get; init; }
    public string Description { get; init; }
    public string Category { get; init; }
    public IReadOnlyDictionary<string, string> UiContributions { get; init; }
    public bool HasSettings { get; init; }
    public bool HasEndpoints { get; init; }
    public IReadOnlyList<string> Dependencies { get; init; }
}

Beachte UiContributions. Dieses Wörterbuch ordnet Frontend-Erweiterungspunkte den Komponentennamen zu, damit das Vue-Frontend weiß, welche UI-Komponenten jedes Plugin beisteuert (eine Schaltfläche in der Symbolleiste, ein Seitenleisten-Panel, eine Einstellungsseite).

Die Registrierung erfolgt in einer Zeile pro Plugin.

Beim Start registrieren wir Plugins über eine fließende API:

var pluginRegistry = new PluginRegistry();

pluginRegistry
    .AddPlugin<WorkflowPluginModule>(builder.Services)
    .AddPlugin<RulesPluginModule>(builder.Services)
    .AddPlugin<RetentionPluginModule>(builder.Services)
    .AddPlugin<ClassificationPluginModule>(builder.Services);

Jeder Aufruf instanziiert das Modul, speichert es in der Registry und ruft RegisterServices() auf, um seine Abhängigkeiten zu verdrahten. Nachdem die App gebaut wurde, werden in einer einzigen Zeile alle Plugin-Routen zugeordnet:

app.MapPluginRoutes(pluginRegistry);

Unter der Haube erhält jedes Plugin unter /api/plugins/{pluginId}/ eine skalierte Routengruppe, auf die automatisch eine Autorisierung angewendet wird.

Reales Beispiel: das Workflow-Plugin

Hier siehst du, wie ein echtes Plugin aussieht, das Modul Workflow & Genehmigungen:

public sealed class WorkflowPluginModule : IPluginModule
{
    public const string PluginId = "workflow";

    public PluginManifest Manifest { get; } = new()
    {
        Id = PluginId,
        Name = "Workflow & Approvals",
        Version = "1.0.0",
        Description = "Adds approval workflows to entry publishing.",
        Category = "Workflow",
        HasSettings = true,
        HasEndpoints = true,
        UiContributions = new Dictionary<string, string>
        {
            ["entry.toolbar.publish"] = "WorkflowPublishButton",
            ["entry.sidebar.status"]  = "WorkflowStatusPanel",
            ["hub.admin.settings"]    = "WorkflowHubSettings",
        }
    };

    public void RegisterServices(IServiceCollection services)
    {
        services.AddScoped<IWorkflowService, WorkflowService>();
        services.AddScoped<IActionGuard, WorkflowPublishGuard>();
    }

    public void MapRoutes(IEndpointRouteBuilder routes)
    {
        WorkflowEndpoints.Map(routes);
    }
}

Die Kernplattform verweist niemals direkt auf WorkflowService oder WorkflowPublishGuard. Sie findet sie über den DI-Container. Das ist der Schlüssel zur Null-Kopplung. Die Kernapplikation berührt nie den Plugin-Code.

Action Guards: die Kontrollschicht

Plugins fügen Fähigkeiten hinzu. Action Guards entscheiden, ob diese Fähigkeit oder eine Kernaktion ausgeführt werden darf. Sie sind synchrone Prüfer, die Operationen vor der Ausführung abfangen.

Aktionswächter-Bewertungsablauf

Die Schnittstelle ist absichtlich minimal:

public interface IActionGuard
{
    string PluginId { get; }
    string? ActionName { get; }  // null means guard ALL actions

    Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default);
}

Wenn ActionName auf null steht, läuft die Wache für jede Aktion. Wenn sie auf etwas wie "Entry.Publish" gesetzt ist, fängt sie nur diese spezielle Aktion ab.

Die Kontext- und Ergebnisverträge

Jeder Guard erhält einen typisierten Kontext mit dem Aktionsnamen, dem Tenant, dem User, der Entität und einer Property Bag:

public sealed record ActionGuardContext(
    string ActionName,
    Guid TenantId,
    Guid UserId,
    Guid EntityId,
    IReadOnlyDictionary<string, object?> Properties)
{
    public T? Get<T>(string key) =>
        Properties.TryGetValue(key, out var v) && v is T typed
            ? typed : default;
}

Und jeder Guard liefert ein vorhersehbares Ergebnis: allow, deny oder allow-with-modifications:

public sealed record ActionGuardResult
{
    public bool IsAllowed { get; init; }
    public string? ReasonCode { get; init; }
    public string? Message { get; init; }
    public IReadOnlyDictionary<string, object?>? Modifications { get; init; }

    public static ActionGuardResult Allow() =>
        new() { IsAllowed = true };

    public static ActionGuardResult Deny(
        string reasonCode, string message) =>
        new() { IsAllowed = false, ReasonCode = reasonCode, Message = message };
}

Das Feld Modifications ist wichtig. Ein Guard kann eine Aktion genehmigen, aber einen Teil des Inhalts umschreiben (zum Beispiel Geheimnisse vor der Veröffentlichung löschen).

Kanonische Aktionsnamen

Wir definieren alle abfangbaren Aktionen als String-Konstanten, damit es keine Unklarheiten darüber gibt, worauf ein Guard abzielen kann:

public static class ActionNames
{
    public static class Entry
    {
        public const string Create  = "Entry.Create";
        public const string Save    = "Entry.Save";
        public const string Publish = "Entry.Publish";
        public const string Delete  = "Entry.Delete";
        public const string Archive = "Entry.Archive";
        public const string Renew   = "Entry.Renew";
    }

    public static class Hub
    {
        public const string Create = "Hub.Create";
        public const string Delete = "Hub.Delete";
        public const string TransferOwnership = "Hub.TransferOwnership";
    }

    public static class Translation
    {
        public const string Create  = "Translation.Create";
        public const string Publish = "Translation.Publish";
    }
}

Reales Beispiel: Veröffentlichen ohne Genehmigung blockieren

Das Workflow-Plugin registriert einen Guard, der Entry.Publish abfängt:

public sealed class WorkflowPublishGuard : IActionGuard
{
    public string PluginId => WorkflowPluginModule.PluginId;
    public string? ActionName => ActionNames.Entry.Publish;

    public async Task<ActionGuardResult> EvaluateAsync(
        ActionGuardContext context,
        IServiceProvider services,
        CancellationToken ct = default)
    {
        var db = services.GetRequiredService<RasepiDbContext>();
        var entry = await db.Entries
            .AsNoTracking()
            .FirstOrDefaultAsync(e => e.Id == context.EntityId, ct);

        if (entry is null)
            return ActionGuardResult.Allow();

        var workflowService = services.GetRequiredService<IWorkflowService>();
        var check = await workflowService
            .CheckPublishAllowedAsync(entry.Id, entry.HubId);

        if (check.IsAllowed)
            return ActionGuardResult.Allow();

        return ActionGuardResult.Deny(
            "workflow.approval_required",
            check.Message ?? "Approval required before publishing.");
    }
}

Die Kernplattform weiß nichts über Genehmigungsworkflows. Sie ruft lediglich Entry.Publish über die Pipeline auf, und der Guard blockiert ihn, wenn der Workflow noch nicht abgeschlossen ist.

Die Aktionspipeline: wo alles zusammenläuft

Der ActionPipeline ist der einzige Ausführungspfad für alle bewachten Vorgänge. Sie entscheidet, welche Guards gelten, wertet sie aus und führt die Aktion entweder aus oder blockiert sie.

public sealed class ActionPipeline : IActionPipeline
{
    public async Task<ActionPipelineResult> ExecuteAsync(
        string actionName,
        ActionGuardContext context,
        Func<Task> action,
        CancellationToken ct = default)
    {
        var result = await EvaluateAsync(actionName, context, ct);
        if (!result.IsAllowed) return result;

        await action();  // All guards passed — execute

        return result;   // Return modifications for caller
    }
}

Die EvaluateAsync-Methode erledigt die schwere Arbeit:

public async Task<ActionPipelineResult> EvaluateAsync(
    string actionName,
    ActionGuardContext context,
    CancellationToken ct = default)
{
    // 1. Which plugins are enabled for this tenant?
    var enabledPlugins = await _resolver.GetEnabledPluginIdsAsync();

    // 2. Which guards match this action?
    var applicable = _guards
        .Where(g => enabledPlugins.Contains(g.PluginId))
        .Where(g => g.ActionName == null || g.ActionName == actionName)
        .ToList();

    // 3. Evaluate each guard
    var denials = new List<ActionGuardResult>();
    var modifications = new List<ActionGuardResult>();

    foreach (var guard in applicable)
    {
        try
        {
            var guardResult = await guard.EvaluateAsync(context, _services, ct);
            if (!guardResult.IsAllowed)
                denials.Add(guardResult);
            else if (guardResult.Modifications?.Count > 0)
                modifications.Add(guardResult);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Guard threw. Treating as Allow.");
        }
    }

    // 4. Any denial blocks the whole action
    if (denials.Count > 0)
        return ActionPipelineResult.Blocked(denials);

    return modifications.Count > 0
        ? ActionPipelineResult.Allowed(modifications)
        : ActionPipelineResult.Allowed();
}

Hier gibt es drei wichtige Designentscheidungen:

Per-Tenant-Auflösung. Der TenantPluginResolver prüft, welche Plugins jeder Tenant installiert und aktiviert hat. Ein Guard für ein deaktiviertes Plugin wird nie ausgeführt.
Alle müssen passieren. Wenn ein Guard verweigert, wird die Aktion blockiert. Dies ist eine bewusste Sicherheitsmaßnahme.
Wächterfehler scheitern offen. Wenn ein Wächter eine Ausnahme auslöst, wird sie protokolliert und als Allow() behandelt. Dadurch wird verhindert, dass ein fehlerhaftes Plugin die gesamte Plattform sperrt.

Pro-Tenant-Plugin-Auflösung

Der Resolver fragt die Tabelle TenantPluginInstallations ab (die durch die globalen Abfragefilter von EF automatisch auf den aktuellen Tenant beschränkt wird):

public sealed class TenantPluginResolver : ITenantPluginResolver
{
    public async Task<IReadOnlySet<string>> GetEnabledPluginIdsAsync(
        CancellationToken ct = default)
    {
        if (_cache is not null) return _cache;

        var ids = await _db.TenantPluginInstallations
            .Where(i => i.IsEnabled)
            .Select(i => i.PluginId)
            .ToListAsync(ct);

        _cache = ids.ToHashSet();
        return _cache;
    }
}

Ereignisgesteuerte Seiteneffekte

Aktionen sind synchron. Seiteneffekte sind es nicht. Nachdem eine Aktion abgeschlossen ist, veröffentlicht der Dienst ein Domänenereignis:

await _eventPublisher.PublishAsync(
    EventNames.Entry.Created, entry.Id, new { entry.OriginalLanguage });

Die Ereignisse werden in einen In-Memory-Kanal eingereiht und von einem EventConsumerWorker im Hintergrund verarbeitet. Der Worker leitet die Ereignisse an mehrere Systeme weiter:

Aktivitätsverfolgung. Protokolliert, wer was wann getan hat.
Übersetzungsabrechnung. Verfolgt die Kosten pro Anbieter
Plugin-Event-Handler. Jedes Plugin kann Domain-Events abonnieren

Plugin-Ereignishandler implementieren IPluginEventHandler:

public interface IPluginEventHandler
{
    string PluginId { get; }
    IReadOnlyList<string> SubscribedEvents { get; }

    Task HandleAsync(
        string eventName, Guid entityId,
        Guid? tenantId, Guid? userId,
        string payloadJson, IServiceProvider services,
        CancellationToken ct = default);
}

Der Worker ruft nur Handler auf, deren Plugin für den Tenant aktiviert ist. Das bedeutet, dass die Nebeneffekte von Plugin A niemals in einen Tenant gelangen, in dem nur Plugin B installiert ist.

Die Übersetzungsmaschine auf Blockebene

Hier macht sich die Architektur am deutlichsten bemerkbar.

Herkömmliche Plattformen übersetzen ganze Dokumente. Wir übersetzen einzelne Blöcke: Absätze, Überschriften, Listenelemente. Wenn ein Benutzer einen Absatz in einem Dokument mit 50 Blöcken bearbeitet, muss nur dieser Absatz neu übersetzt werden. Das ist der Grund für unsere 94%ige Kostenersparnis.

Wie Blöcke aus TipTap JSON erstellt werden

Wenn ein Benutzer ein Dokument speichert, sendet der TipTap-Editor JSON wie folgt:

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "attrs": { "blockId": "a1b2c3d4-..." },
      "content": [{ "type": "text", "text": "Hello world" }]
    }
  ]
}

Der BlockTranslationService parst dieses JSON und erstellt einzelne EntryBlock Datensätze:

public async Task<List<EntryBlock>> CreateBlocksFromDocumentAsync(
    Guid entryId, string language, string contentJson,
    int version, Guid userId)
{
    var doc = JsonDocument.Parse(contentJson);
    var content = doc.RootElement.GetProperty("content");

    int position = 0;
    foreach (var node in content.EnumerateArray())
    {
        var blockType = node.GetProperty("type").GetString();
        var blockJson = JsonSerializer.Serialize(node);

        // Strip metadata attrs before hashing
        var hashInput = StripBlockMetaAttrs(blockJson);

        var block = new EntryBlock
        {
            Id = ExtractOrGenerateBlockId(node),
            EntryId = entryId,
            Language = language,
            Position = position++,
            BlockType = blockType,
            ContentJson = blockJson,
            ContentHash = CalculateContentHash(hashInput),
            IsNoTranslate = ExtractNoTranslateFlag(node),
            Version = version,
        };

        _context.EntryBlocks.Add(block);
    }

    await _context.SaveChangesAsync();
    return blocks;
}

SHA256 Hashing für Stale-Erkennung

Der Inhalts-Hash ist das Herzstück der Stale Detection. Wir hashen den Blockinhalt (nachdem wir Metadatenattribute wie blockId und deleted entfernt haben) mit SHA256:

private string CalculateContentHash(string content)
{
    using var sha256 = SHA256.Create();
    var hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(content));
    return Convert.ToHexString(hashBytes);
}

Wenn sich ein Quellblock ändert, ändert sich auch sein Hash. Das System vergleicht dann den SourceContentHash jedes Übersetzungsblocks mit dem aktuellen Quell-Hash und markiert Unstimmigkeiten als Stale:

public async Task MarkTranslationsAsStaleAsync(List<Guid> changedBlockIds)
{
    var affected = await _context.TranslationBlocks
        .Where(t => changedBlockIds.Contains(t.SourceBlockId))
        .ToListAsync();

    foreach (var translation in affected)
    {
        translation.Status = TranslationStatus.Stale;
        translation.UpdatedAt = DateTime.UtcNow;
    }

    await _context.SaveChangesAsync();
}

Strukturanpassung

Übersetzer können die Blocktypen in verschiedenen Sprachen ändern. Eine englische Aufzählungsliste kann zu einer deutschen nummerierten Liste werden, eine kulturelle Präferenz. Das System verfolgt dies:

var translation = new TranslationBlock
{
    SourceBlockId = sourceBlockId,
    Language = targetLanguage,
    BlockType = translatedBlockType,
    SourceBlockType = sourceBlock.BlockType,
    IsStructureAdapted = translatedBlockType != sourceBlock.BlockType,
    SourceContentHash = sourceBlock.ContentHash,
    Status = TranslationStatus.UpToDate,
};

Übersetzungsanbieter als Plugins

Externe Übersetzungsdienste (DeepL, Google Translate, etc.) werden über ITranslationProviderPlugin eingebunden:

public interface ITranslationProviderPlugin : IRasepiPlugin
{
    string[] GetSupportedLanguages();

    Task<string> TranslateAsync(
        string text, string sourceLanguage, string targetLanguage);

    Task<TranslationBatchResult> TranslateBatchAsync(
        Dictionary<string, string> texts,
        string sourceLanguage, string targetLanguage);
}

Die Batch-Methode erhält ein Wörterbuch mit den Block-IDs zum Inhalt, übersetzt sie alle und gibt die Übersetzungen mit einer abgerechneten Zeichenanzahl zurück. Da wir nur veraltete Blöcke und nicht das gesamte Dokument versenden, bleiben die Kosten minimal.

Mieterisolierung: das unsichtbare Sicherheitsnetz

Jedes der oben beschriebenen Systeme läuft innerhalb einer strengen Tenant Isolation.

Der TenantContextMiddleware löst bei jeder Anfrage den Tenant aus dem JWT auf und verifiziert die Mitgliedschaft:

public async Task InvokeAsync(
    HttpContext context, TenantContext tenantContext, RasepiDbContext db)
{
    var tenantIdClaim = context.User.FindFirstValue("tenant_id");
    var userIdClaim = context.User.FindFirstValue(ClaimTypes.NameIdentifier);

    // Populate scoped context
    tenantContext.TenantId = Guid.Parse(tenantIdClaim);
    tenantContext.UserId = Guid.Parse(userIdClaim);

    // Verify membership — fail closed
    var membership = await db.TenantMemberships
        .Where(m => m.TenantId == tenantContext.TenantId
                  && m.UserId == tenantContext.UserId)
        .FirstOrDefaultAsync();

    if (membership == null)
    {
        context.Response.StatusCode = 401;
        return;  // No membership = no access
    }
}

Die globalen Abfragefilter von Entity Framework stellen sicher, dass die Datenbankschicht die Filterung nach Tenant automatisch vornimmt, selbst wenn ein Entwickler sie vergisst:

modelBuilder.Entity<Hub>()
    .HasQueryFilter(h => h.TenantId == _tenantContext.TenantId);

Das Ergebnis: db.Hubs.ToListAsync() gibt immer nur die Hubs des aktuellen Tenants zurück. Für Datenlecks muss der Abfragefilter aktiv umgangen werden, was in unserer Codebasis verboten ist.

Das vollständige Bild

Wenn ein Nutzer bei einem Eintrag auf "Veröffentlichen" klickt, passiert folgendes:

Die Anfrage wird eingegeben Die Authentifizierung validiert den JWT, TenantContextMiddleware löst auf und verifiziert den Tenant.
Controller ruft die Pipeline auf. IActionPipeline.ExecuteAsync("Entry.Publish", context, action)
Pipeline löst Wachen auf. Fragt ab, welche Plugins der Tenant aktiviert hat, und wählt die entsprechenden Wachen aus.
Guards bewerten. Der Workflow-Guard prüft auf Genehmigungen, der Retention-Guard auf Richtlinien, der Rules-Guard validiert den Inhalt. Alle bestanden? Der Eintrag wird veröffentlicht.
Ereignisse werden ausgelöst. Das Ereignis Entry.Published wird in die Warteschlange gestellt. Ein Hintergrundworker protokolliert die Aktivitäten, aktualisiert die Übersetzungsabrechnung und ruft die Plugin-Event-Handler auf.
Übersetzungen von Blöcken werden überprüft. Veraltete Blöcke werden zur Neuübersetzung identifiziert.

Jede Ebene erledigt ihre Arbeit. Keine Schicht greift in eine andere ein. Das ist die Architektur.

Wir haben sie nicht gebaut, weil Erweiterbarkeit in Mode ist. Wir haben sie gebaut, weil eine Dokumentationsplattform, die sich nicht an die Arbeitsabläufe der einzelnen Teams anpassen kann, irgendwann durch eine ersetzt wird, die das kann. Und eine Plattform, die sich ohne Leitplanken anpasst, wird irgendwann etwas kaputt machen, das wichtig ist.