In Arbeit01 · Werkzeugwand7 Min. Lesezeit

Wie OpenFolia entsteht

Ich habe das Dokumentationssystem gebaut, das ich kaufen wollte. OpenFolia speichert Betriebsanleitungen als kleine Module in einfachen Dateien, die dem Hersteller gehören, und baut daraus für jede Produktvariante und jede Sprache eine korrekte Anleitung. Es ist kostenlos und Open Source.

BauzeitCommitsTestdateienLizenz
5 Tage (17. bis 21. Nov. 2026)2.230701AGPL-3.0

Das Problem

Ein Maschinenbauer verkauft selten nur eine Maschine. Er verkauft ein großes und ein kleines Modell, für mehrere Märkte, mit Optionen und Softwareversionen, die sich jedes Jahr ändern. Jede Kombination braucht eine Betriebsanleitung, meist in einem Dutzend Sprachen.

Die meisten Teams lösen das durch Kopieren. Eine Korrektur landet in einer Kopie und nicht in den anderen zehn. Jede kleine Änderung schickt die ganze Anleitung wieder zur Übersetzung. In der Sicherheitsdokumentation ist ein Warnhinweis, der für eine Variante falsch ist, ein Haftungsrisiko und kein Tippfehler.

Software, die das löst, gibt es: ein Component Content Management System, kurz CCMS. Nach meiner Erfahrung war es teuer, geschlossen, langsam in der Arbeit und schwer zu verlassen, sobald die Inhalte einmal drin waren. Nach einer schlechten Runde mit einem Anbieter habe ich beschlossen, das Werkzeug zu bauen, das ich hatte kaufen wollen.

OpenFolia ist für Technische Redakteure und Dokumentationsverantwortliche bei Herstellern: Maschinen, Geräte, alles, was mit einer Anleitung und einem Sicherheitsblatt ausgeliefert wird.

Die Idee: einmal schreiben, alles zusammenbauen

Inhalte werden als kleine Module geschrieben: eine Handlungsanweisung, ein Sicherheitshinweis, ein Kapitel zum Laden. Eine Anleitung ist eine Gliederung, die auf Module verweist. Ein Build ist eine Anleitung für eine Variante in einer Sprache. Ein Release ist ein unveränderlicher Snapshot von allem.

Die Entscheidung, aus der alles andere folgt: Die Module liegen als AsciiDoc-Dateien in einem Git-Repository, das dem Kunden gehört. Die Datenbank hält nur, was Menschen und Abläufe betrifft: Benutzer, Rollen, Sperren, Kommentare, Workflow, das Audit-Log und einen Suchindex, der sich jederzeit aus den Dateien neu aufbauen lässt. Wenn du gehst, nimmst du einfachen Text mit. Es gibt nichts zu exportieren.

Architekturdiagramm mit dem Titel 'Every output reads from the content repository through one API'. Links speisen das Content-Repository (AsciiDoc-Module, Anleitungen, Begriffe und ccms.yaml in Git, hervorgehoben) und Postgres (Menschen, Workflow, Sperren und ein neu aufbaubarer Index) beide die JSON:API in der Mitte (jeder Branch, Tag oder Commit; OpenAPI aus dem Code generiert). Die API bedient rechts vier Ausgaben: den Web-Editor (ein Client der API), PDF/UA-1 und HTML (Typst, jede Variante), Portale und Systeme (iiRDS-Export, Webhooks) und den MCP-Server (KI-Assistenten, nur lesend).
Architektur · eine Quelle, eine API, vier Ausgaben

Die Dateien sind die Quelle der Wahrheit, Postgres hält nur, was Menschen und Abläufe betrifft.

OpenFolia ist ab dem ersten Commit headless. Der Editor hat keine private Hintertür: Alles, was er tut, geht über die dokumentierte JSON:API. Die OpenAPI-Beschreibung wird aus dem Code generiert, und die End-to-End-Tests prüfen jede Antwort dagegen, sodass die API-Dokumentation nicht von der API abweichen kann.

Stack: durchgehend TypeScript. Eine NestJS-API in hexagonaler Architektur, ein Angular-Editor auf ProseMirror, Typst für PDF, Postgres, S3-kompatibler Speicher. Ein Nx-Monorepo mit Vitest und Playwright.

Drei Probleme, die es wert sind, ordentlich gelöst zu werden

Varianten ohne Kopien

Was sich zwischen Varianten unterscheidet, wird mit einer Bedingung in einer kleinen, typisierten Ausdruckssprache markiert. Versionsattribute werden als Zahlen verglichen, also ist software >= 2.10 wahr für 2.10 und falsch für 2.9, was ein reiner Textvergleich falsch macht.

[variant#lift-limit,when="model in (large) && software >= 2.3"]
====
The lift stops at {max-height}. Do not override the limit.
====

Redakteure tippen das nie. Im Editor baut eine Auswahl die Regel, liest sie als Satz vor und zeigt live, wie viele ausgelieferte Builds sie trifft („Appears in 6 builds“). Die Vorschau nennt, was die aktuelle Variante ausblendet. Vor einem Release wird jede ausgelieferte Variante in jeder Sprache aufgelöst, und ein unbekanntes Attribut oder ein fehlender Wert blockiert das Release.

Eine bewusste Grenze: Bedingungen wirken auf ganze Blöcke, nicht innerhalb eines Satzes. Wörter, die sich je Modell ändern, etwa eine maximale Höhe, sind Textattribute. So bleibt jeder Satz ganz, und das ist für die Übersetzung wichtig.

Nur übersetzen, was sich geändert hat

Jeder übersetzte Block merkt sich einen SHA-256-Hash des Ausgangstexts, aus dem er übersetzt wurde. Der Hash ignoriert Umformatierungen, ein verschobener Zeilenumbruch bewirkt also nichts, während ein geändertes Wort genau diesen Block als veraltet markiert. Der Zustand jedes Blocks in jeder Sprache wird bei jeder Anfrage aus den Dateien abgeleitet und nie von Hand gepflegt.

Der Export an ein Übersetzungsbüro ist ein Delta in XLIFF 2.0, dem OASIS-Standard: nur veraltete oder fehlende Einheiten, mit Wortzahlen, bevor du ihn abschickst. Eine Einheit kann nur in einem offenen Auftrag sein, also wird nichts doppelt bezahlt. Auf dem Rückweg wird jede Einheit geprüft, und der Import wird ein Entwurf, der durch das normale Review geht. Ein Übersetzer kann kein Linkziel ändern, und der XML-Parser lehnt DTDs und Entities ab, sodass eine bösartige Datei den Server nicht auslesen kann.

Druckreife Ausgabe in etwa einer Sekunde

Anleitungen werden über Typst als getaggtes, barrierefreies PDF/UA-1 gerendert, ohne DTP-Schritt und ohne eigene Lizenz für einen Rendering-Server. Sicherheitshinweise folgen ISO 3864 und ANSI Z535: Signalwort, Farbe und Symbol.

Templates sind einfacher Text im selben Repository wie die Inhalte, also wird eine Layoutänderung wie jede andere Änderung geprüft und versioniert. Das Rendern ist schnell genug für eine Vorschau beim Schreiben, und das verändert, wie Leute schreiben.

Geschwindigkeit ist ein Test, keine Hoffnung

Geschwindigkeitsziele laufen bei jeder Änderung im Build mit: eine Modulvorschau unter 1 Sekunde, eine Suche unter 300 Millisekunden, das PDF einer Anleitung unter 3 Sekunden kalt und unter 1 Sekunde für eine weitere Variante. Eine Änderung, die sie bricht, schlägt fehl.

Die erste Messung im großen Maßstab lief auf einem generierten Repository mit 5.542 Modulen, 300 Anleitungen und 8 Sprachen:

WasKaltWarm oder nächste Variante
PDF einer Anleitung mit 400 Modulen1,2 s514 ms
PDF einer typischen Anleitung765 ms202 ms
Modulvorschau128 ms48 ms
Volltextsuche4,8 s (erste Abfrage nach einem Neustart)118 ms
Probelauf des XLIFF-Exports145 ms
Serverstart1,24 s (Median)

Gemessen auf einem Laptop mit 16 Kernen, in ruhigen Läufen.

KI-Zugriff, mit Bedacht

Ein MCP-Server gibt KI-Assistenten Zugriff auf die Dokumentation, sodass ein Servicetechniker einen Chat-Assistenten fragen kann, wie man bei einem Modell einen Filter wechselt, und die freigegebene Antwort bekommt. Er ist nur lesend und liefert nur freigegebene Inhalte. Entwürfe gelangen nie in eine Antwort, und ein Assistent kann nie eine Anleitung ändern. Für Teams, die ihr eigenes Retrieval bauen, liefert die API fertige Chunks.

Es gibt außerdem ein optionales Stil-Review, das ein Modul mit einem beliebigen Chat-Modell gegen den Hausstil prüft, auch mit einem selbst gehosteten. Es ist standardmäßig aus und schickt nur den Text des Moduls.

Wie eine Person es in fünf Tagen gebaut hat

Der erste Commit ist vom 17. November 2026. Am 21. hatte das Repository 2.230 Commits und über 900 gemergte Branches. Das habe ich nicht alles selbst getippt. Ich habe als Architekt und Reviewer für ein Team von KI-Coding-Agents gearbeitet, die parallel liefen.

  • Specs als Issues. Die Anforderungen wurden zu einem Backlog aus GitHub-Issues. Das Issue und seine Kommentare sind die Spec, und dort festgehaltene Entscheidungen sind verbindlich.
  • Ein Slot pro Agent. Ein kleines Tool gibt jedem Agent seinen eigenen Worktree, Branch, Port und seine eigene Datenbank, sodass mehrere gleichzeitig arbeiten, ohne sich in die Quere zu kommen.
  • Regeln, die halten. Die schriftlichen Regeln werden durchgesetzt, wo es geht: Eine Lint-Regel hält den Domain-Kern frei von HTTP- und Datenbankcode, der API-Vertrag wird in jedem End-to-End-Test geprüft, und die Geschwindigkeitsbudgets laufen im Build.
  • Ein Review, das lernt. Jeder Agent meldet seine Review-Befunde in einem festen Format. Eine Art von Fehler, die immer wieder auftaucht, wird zu einer Regel, einem Check oder einer Zeile im Prompt.

Meine Arbeit hat sich verschoben: weg vom Code schreiben, hin zu entscheiden, was gebaut wird, präzise Specs schreiben und Nein sagen. Das Schwierige war nicht die Geschwindigkeit. Es war, 2.000 Commits stimmig zu halten.

Open Source, und was das hier heißt

Der Kern steht unter AGPL-3.0 und ist vollständig. Jede Dokumentationsfunktion ist darin: Varianten, Übersetzungen, Reviews und Releases, PDF und HTML, die API und der MCP-Server. Bezahlte Pläne, wenn sie kommen, dürfen nur Hosting, Support und IT-Kontrollen wie Single Sign-on hinzufügen.

Es läuft auf deiner eigenen Infrastruktur: vier Container und Postgres aus einer Compose-Datei. Jedes Image läuft als Benutzer ohne Rechte auf einem schreibgeschützten Dateisystem, mit verschlüsselten und geprüften Backups.

AusgeliefertAls Nächstes
Varianten, Auswahl und Vorschau je VarianteAnmeldung per OpenID Connect im Kern
XLIFF-2.0-Delta-Export und geprüfter ImportEin gehostetes Angebot
Review, Freigabe und Releases mit Git-TagsSSO, SCIM und Export des Audit-Logs für größere Teams
PDF/UA-1- und HTML-AusgabeBildbeschriftungen je Variante
JSON:API, Webhooks und der MCP-ServerCOTI für Übersetzungssysteme
Container-Images und eine Anleitung zum Selbsthosten

Was ich mitnehme

Das Format zu besitzen ist das Feature. Das meiste, was OpenFolia angenehm macht, folgt daraus, dass Inhalte einfacher Text in Git sind: Historie gratis, Review gratis, kein Lock-in, und Ausgaben, die einfach Funktionen eines Commits sind.

Grenzen machen ein Produkt. Nein zu Bedingungen innerhalb von Sätzen, zu einer privaten Editor-API und zu herstellerspezifischen Importern im Kern hat das System klein genug gehalten, um schnell und korrekt zu bleiben.

Mit Agents zu bauen ist mehr ein Führungsproblem als ein Programmierproblem. Die Qualität kam aus Specs, Regeln und Checks, nicht aus einem einzelnen cleveren Prompt.

Links: openfolia.com · docs.openfolia.com · Quellcode auf GitHub

Alle Notizen