Dokumentation #137

Closed
opened 2026-11-06 09:22:35 +01:00 by miko · 2 comments
Owner

Es wird eine Anwender- sowie Administrationsdokumentation für kataba benötigt. Diese kann z.B. mit mkDocs realisiert werden und sollte in der Anwendung verlinkt sein.

Tasks

  • #138 Handbook: Zensical skeleton, ADR and publishing to git-pages
  • #139 Handbook: administration handbook, operator content moved out of the README
  • #140 Handbook: generate screenshots with Playwright
  • #141 Handbook: user handbook for readers and authors (after #140)
  • #142 Link the handbook from the app (after #138)
Es wird eine Anwender- sowie Administrationsdokumentation für kataba benötigt. Diese kann z.B. mit mkDocs realisiert werden und sollte in der Anwendung verlinkt sein. ## Tasks - [x] #138 Handbook: Zensical skeleton, ADR and publishing to git-pages - [x] #139 Handbook: administration handbook, operator content moved out of the README - [x] #140 Handbook: generate screenshots with Playwright - [x] #141 Handbook: user handbook for readers and authors (after #140) - [x] #142 Link the handbook from the app (after #138)
Author
Owner

Ergebnis der Klärung

  • Zwei Handbücher: User handbook (Leser kurz, Autoren ausführlich) und Administration handbook (Admin-Bereich + Betrieb). Vorerst nur Englisch.
  • Zensical statt Material for MkDocs: Material ist seit 2025-11-05 im Wartungsmodus, Support endete 2026-11-05; MkDocs 2.0 bricht Plugins/Themes. Zensical ist der Nachfolger vom Material-Team.
  • Quellen in handbook/ im Repo; Zensical-Version gepinnt, Python bleibt aus dem Node-Projekt heraus.
  • Betriebsinhalte ziehen aus der README in die Doku; die README wird verschlankt.
  • Hosting auf git-pages: https://pages.mike-ochmann.de/kataba/. Nur der aktuelle Release, keine Versionen.
  • Deploy als Schritt im Release-Skill (zensical build --strict → pages-Branch → PUT), kein Runner.
  • Screenshots per Playwright mit eigenen Seed-Daten, manuell erzeugt, committet; hell, Englisch, fester Viewport.
  • In der App: „Help“ im UserMenu → User handbook, Link im Admin-Bereich → Administration handbook; kein Link für Gäste; URL als Konstante.
  • Festgehalten in ADR-0024.

Bewusst draußen: kontextsensitive Hilfe-Links, Forgejo Action/Runner, deutsche Übersetzung, versionierte Doku.

## Ergebnis der Klärung - **Zwei Handbücher**: User handbook (Leser kurz, Autoren ausführlich) und Administration handbook (Admin-Bereich + Betrieb). Vorerst **nur Englisch**. - **Zensical** statt Material for MkDocs: Material ist seit 2025-11-05 im Wartungsmodus, Support endete 2026-11-05; MkDocs 2.0 bricht Plugins/Themes. Zensical ist der Nachfolger vom Material-Team. - Quellen in **`handbook/`** im Repo; Zensical-Version gepinnt, Python bleibt aus dem Node-Projekt heraus. - Betriebsinhalte **ziehen aus der README in die Doku**; die README wird verschlankt. - Hosting auf **git-pages: `https://pages.mike-ochmann.de/kataba/`**. Nur der aktuelle Release, keine Versionen. - Deploy als **Schritt im Release-Skill** (`zensical build --strict` → `pages`-Branch → PUT), kein Runner. - **Screenshots per Playwright** mit eigenen Seed-Daten, manuell erzeugt, committet; hell, Englisch, fester Viewport. - In der App: **„Help“ im UserMenu** → User handbook, **Link im Admin-Bereich** → Administration handbook; kein Link für Gäste; URL als Konstante. - Festgehalten in **ADR-0024**. **Bewusst draußen**: kontextsensitive Hilfe-Links, Forgejo Action/Runner, deutsche Übersetzung, versionierte Doku.
Author
Owner

All sub-tickets are done and merged into development: #138 (Zensical skeleton, ADR-0024, git-pages publishing), #139 (administration handbook, #146), #140 (Playwright screenshots, #144), #141 (user handbook, #145), #142 (handbook linked from the app, #147). The handbook will be published to https://pages.mike-ochmann.de/kataba/ with the next release.

All sub-tickets are done and merged into development: #138 (Zensical skeleton, ADR-0024, git-pages publishing), #139 (administration handbook, #146), #140 (Playwright screenshots, #144), #141 (user handbook, #145), #142 (handbook linked from the app, #147). The handbook will be published to https://pages.mike-ochmann.de/kataba/ with the next release.
miko closed this issue 2026-11-06 11:57:10 +01:00
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba#137
No description provided.