diff --git a/decisions/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md b/decisions/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md new file mode 100644 index 0000000..2913eb4 --- /dev/null +++ b/decisions/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md @@ -0,0 +1,66 @@ +# 0007 — Wiki-Oberfläche: Docusaurus läuft, BookStack als Gegenentwurf + +**Status:** vorgeschlagen (Entscheidung offen → [Issue #20](https://git.lab/axion1337.chat/management/-/issues/20)) · **Datum:** 2026-08-02 · **Entscheider:** sorb + +## Kontext + +[ADR-0006](0006-wikis-konsolidieren-docusaurus.md) hat die Wikis ins Lab geholt und +Docusaurus als Lesefläche gebaut — läuft seit 2026-08-02 unter `axionwiki.lab`. +Danach kam der Wunsch nach einer BookStack-Variante, angeregt von der +[ESS-Dokumentation von Element](https://ems-docs.element.io/), die selbst auf +BookStack läuft und sehr aufgeräumt wirkt. + +Beide Werkzeuge lösen dieselbe Aufgabe grundverschieden — deshalb ist das keine +Werkzeugwahl, sondern eine Weichenstellung. + +## Entscheidung + +**Beide Varianten existieren parallel, bis an echten Inhalten entschieden wird.** +Docusaurus bleibt vorerst der produktive Weg (`axionwiki.lab`, läuft), BookStack +kommt als Vergleichsentwurf daneben (`bookstack.lab`, Repo +[homelab/wiki-bookstack](https://git.lab/homelab/wiki-bookstack)). + +Die eigentliche Entscheidung wird **vertagt** — bewusst, weil sie an einer Frage +hängt, die sich am Reißbrett nicht beantworten lässt: Soll Dokumentation künftig +**im Repo** entstehen oder **im Browser**? + +## Der Unterschied, auf den es ankommt + +| | Docusaurus | BookStack | +|---|---|---| +| Wo der Text lebt | in den Quell-Repos, beim Bau eingesammelt | **in einer Datenbank** | +| Wie geändert wird | Commit, Review, Git-Historie | WYSIWYG im Browser | +| Betrieb | statisches Image, zustandslos | Anwendung + MariaDB, **backup-pflichtig** | +| Suche | fehlt (Plugin nötig) | eingebaut | +| Rechte | alles oder nichts | je Buch/Regal | +| Quelle der Wahrheit | eindeutig das Repo | **die Datenbank — neben den Repos** | + +Die letzte Zeile ist der Kern. Mit BookStack entsteht eine zweite Quelle der +Wahrheit neben git.lab — genau das, was [ADR-0002](0002-issues-und-management-ins-lab.md) +für Issues gerade aufgelöst hat. Das kann richtig sein (Dokumentation hat andere +Autoren und Lebenszyklen als Code), muss aber bewusst entschieden werden. + +## Konsequenzen + +- **Doppelter Betrieb auf Zeit.** Zwei Stacks, zwei Domains. Vertretbar, solange es + ein Vergleich ist; auf Dauer ist es Ballast — deshalb gehört zu dieser Entscheidung + ein Verfallsdatum. +- **BookStack braucht ein Backup, sobald es mehr als ein Versuch ist.** Eine + Datenbank ohne Sicherung ist eine Zeitbombe (vgl. CFGMON-09, wo genau das seit + 2026-07-30 offen ist). +- **Kein Importer, solange nichts entschieden ist** (`import/` bleibt leer). Ein + Import wäre eine Einbahnstraße und würde Synchronität vortäuschen, die es nicht gibt. +- Die **Themes sind farbgleich** zu den Element-Themes (Gruvbox Dark und Sunset + Boulevard), damit der Vergleich nicht an der Optik hängt, sondern am Arbeitsmodell. +- Die Verliererseite wird **abgeräumt**, nicht „für später" behalten. + +## Verworfene Alternativen + +- **Direkt auf BookStack wechseln:** Docusaurus läuft bereits und kostet nichts im + Betrieb; ein Wechsel ohne belastbaren Vergleich wäre Geschmacksentscheidung. +- **BookStack gar nicht ausprobieren:** Die Frage „im Repo oder im Browser + schreiben?" ist real und betrifft künftig jede Doku — sie lässt sich nur an + echten Inhalten beantworten. +- **Beides dauerhaft parallel:** zwei Quellen der Wahrheit für dieselben Inhalte, + garantierte Drift. Genau der Zustand, den der Wiki-Audit vom 2026-08-02 aufgedeckt + hat (drei auseinandergelaufene Stände). diff --git a/roadmap.md b/roadmap.md index a5c3009..739eebc 100644 --- a/roadmap.md +++ b/roadmap.md @@ -28,7 +28,11 @@ 2. GAME-01-Erreichbarkeit + vSwitch-Aufnahme — [#2](https://git.lab/axion1337.chat/management/-/issues/2) (Silences bis 2026-08-04!) 3. Roadmap-/Board-Ausbau in GitLab (Rest von gitops#46: Milestones, Boards). -4. Sicherheits-Nachlese aus der VPN-Nacht: +4. **Wiki-Oberfläche entscheiden** — [DOC-03 (#20)](https://git.lab/axion1337.chat/management/-/issues/20): + Docusaurus läuft (`axionwiki.lab`), BookStack steht als Gegenentwurf bereit + ([ADR-0007](decisions/0007-wiki-oberflaeche-docusaurus-vs-bookstack.md)). Die Frage + dahinter: Doku im Repo oder im Browser? Verfallsdatum Ende August. +5. Sicherheits-Nachlese aus der VPN-Nacht: [CFGMON-14 (#14)](https://git.lab/axion1337.chat/management/-/issues/14) docker-Gruppe = root-äquivalent (Entscheidung sorb), [CFGMON-15 (#15)](https://git.lab/axion1337.chat/management/-/issues/15) Token-Hygiene,