📖 🤖 Doku-Housekeeping je Release: README/docs aktuell, lesbar, Screenshots (Web-Editor) #131

Open
opened 2026-11-04 18:37:01 +01:00 by holm · 13 comments
Owner
Dimension Bewertung Einschätzung
Aufwand ███░░░░░░░ Niedrig-mittel je Release — ein Worker-Lauf
Nutzen █████████░ Sehr hoch — „das beste Tooling bringt nix, wenn es niemand bedienen kann“
Bruchhäufigkeit ███████░░░ Hoch — jedes Feature-Release (rc.18: #106, #125, #127, #129) ändert Befehle/Config
Nachhaltigkeit ████████░░ Hoch — als fester Release-Schritt
Dringlichkeit █████░░░░░ Mittel — erster Lauf mit dem nächsten Release (#126/#128)

Ziel (Holm 2026-11-04)

„readme und dokumentation stets auf dem aktuellen stand halten lassen. das ist ein housekeeping worker bei oder nach jedem release. das beste tooling bringt nix wenns niemand bedienen kann. und die beste markdown bringt nix wenn sie haesslich angelegt ist und sie niemand lesen kann oder will. screenshots wären auch geil falls möglich. insbesondere von der web-UI.“

Release-Schritt „Doku-Housekeeping“ (bei/nach jedem Release, v00 dispatcht)

  1. Abgleich Doku ↔ Code: README, docs/*.md, TEMPLATE.md gegen zpub --help/Aufruf-Block, build.sh-Optionen, Config-Schlüssel (podcast.toml-Beispiel aus zpub init), Template-Variablen; neue Features des Release aus CHANGELOG (git-cliff) nachziehen; Altes entfernen (z. B. feeds/interval #106)
  2. Lesbarkeit: Quickstart zuerst, Tabellen statt Fließtext, kurze Abschnitte, einheitliche Überschriften, Inhaltsverzeichnis je docs-Datei, funktionierende relative Links (prüfen)
  3. Screenshots (docs/screenshots/): Site (Index, Folge, Player läuft, Suche, Pagination) und Web-Editor (webwizard) — headless Chromium/Firefox (vorhanden: scripts/check/spa-*.mjs), reproduzierbar per Script scripts/docs-screenshots.sh (Bash + node, kein Python), feste Fenstergröße, hell/dunkel falls vorhanden; Bilder optimiert (magick/pngquant), alt-Texte
  4. Prüfbar: Link-Check der Markdown-Dateien; Liste „Config-Schlüssel ohne Doku“ / „Doku-Schlüssel ohne Code“ als Script-Ausgabe
  5. Ergebnis als eigener Commit docs: Housekeeping vX mit Refs auf dieses Issue; Issue bleibt als Dauer-Checkliste offen, je Release ein Beleg-Kommentar

Schwächster Punkt

Screenshots veralten mit jedem Design-Tweak — nur sinnvoll, wenn das Script sie reproduzierbar erzeugt; Web-Editor braucht einen laufenden lokalen Server mit Beispiel-Tenant (Port, Aufräumen).

🤖 angelegt von Claude v00 (API/Token holm)

| Dimension | Bewertung | Einschätzung | |---|---|---| | Aufwand | `███░░░░░░░` | Niedrig-mittel je Release — ein Worker-Lauf | | Nutzen | `█████████░` | Sehr hoch — „das beste Tooling bringt nix, wenn es niemand bedienen kann“ | | Bruchhäufigkeit | `███████░░░` | Hoch — jedes Feature-Release (rc.18: #106, #125, #127, #129) ändert Befehle/Config | | Nachhaltigkeit | `████████░░` | Hoch — als fester Release-Schritt | | Dringlichkeit | `█████░░░░░` | Mittel — erster Lauf mit dem nächsten Release (#126/#128) | ## Ziel (Holm 2026-11-04) > „readme und dokumentation stets auf dem aktuellen stand halten lassen. das ist ein housekeeping worker bei oder nach jedem release. das beste tooling bringt nix wenns niemand bedienen kann. und die beste markdown bringt nix wenn sie haesslich angelegt ist und sie niemand lesen kann oder will. screenshots wären auch geil falls möglich. insbesondere von der web-UI.“ ## Release-Schritt „Doku-Housekeeping“ (bei/nach jedem Release, v00 dispatcht) 1. **Abgleich Doku ↔ Code:** README, docs/*.md, TEMPLATE.md gegen `zpub --help`/Aufruf-Block, build.sh-Optionen, Config-Schlüssel (podcast.toml-Beispiel aus `zpub init`), Template-Variablen; neue Features des Release aus CHANGELOG (git-cliff) nachziehen; Altes entfernen (z. B. feeds/interval #106) 2. **Lesbarkeit:** Quickstart zuerst, Tabellen statt Fließtext, kurze Abschnitte, einheitliche Überschriften, Inhaltsverzeichnis je docs-Datei, funktionierende relative Links (prüfen) 3. **Screenshots** (docs/screenshots/): Site (Index, Folge, Player läuft, Suche, Pagination) **und Web-Editor (webwizard)** — headless Chromium/Firefox (vorhanden: scripts/check/spa-*.mjs), reproduzierbar per Script `scripts/docs-screenshots.sh` (Bash + node, kein Python), feste Fenstergröße, hell/dunkel falls vorhanden; Bilder optimiert (magick/pngquant), alt-Texte 4. **Prüfbar:** Link-Check der Markdown-Dateien; Liste „Config-Schlüssel ohne Doku“ / „Doku-Schlüssel ohne Code“ als Script-Ausgabe 5. Ergebnis als eigener Commit `docs: Housekeeping vX` mit Refs auf dieses Issue; Issue bleibt als Dauer-Checkliste offen, je Release ein Beleg-Kommentar ## Schwächster Punkt Screenshots veralten mit jedem Design-Tweak — nur sinnvoll, wenn das Script sie reproduzierbar erzeugt; Web-Editor braucht einen laufenden lokalen Server mit Beispiel-Tenant (Port, Aufräumen). > 🤖 angelegt von Claude v00 (API/Token holm)
Author
Owner

Lauf rc.19 — gemergt nach dev (721e8fc)

Punkt Ergebnis
scripts/check/docs-drift.sh (neu) vorher 18 Befunde (7 Config ohne Doku, 8 Template-Variablen, 3 Befehle) → 0; Link-Prüfung belegt wirksam
scripts/docs-screenshots.sh (neu) 11 Screenshots reproduzierbar: Website (index, Player, Panel, Folge, Suche, Pagination) + Web-Editor (leer, neue Folge, angelegt, Liste); v00 hat das Script nach den Editor-Fixes erneut laufen lassen
README Quickstart nachgefahren (init → episode new → build → check → deploy), Screenshot-Galerie
docs/* Inhaltsverzeichnisse, „Entfallene Schlüssel“, rc.19-Features geprüft; player.md wegen #130 unberührt
Code-Befunde Staffel-Feld ungestylt, absoluter Serverpfad in API-Antwort, veralteter „build.sh“-Text im Editor → #136, behoben

Grenzen: drift-Erkennung per grep (berechnete Pfade unsichtbar); Inhaltszeilen werden nicht auf neue Abschnitte geprüft; zentonic26 hat keinen Hellmodus.

Issue bleibt offen (Dauer-Checkliste je Release).

🤖 angelegt von Claude v00 (API/Token holm)

## Lauf rc.19 — gemergt nach dev (721e8fc) | Punkt | Ergebnis | |---|---| | `scripts/check/docs-drift.sh` (neu) | vorher 18 Befunde (7 Config ohne Doku, 8 Template-Variablen, 3 Befehle) → 0; Link-Prüfung belegt wirksam | | `scripts/docs-screenshots.sh` (neu) | 11 Screenshots reproduzierbar: Website (index, Player, Panel, Folge, Suche, Pagination) + **Web-Editor** (leer, neue Folge, angelegt, Liste); v00 hat das Script nach den Editor-Fixes erneut laufen lassen | | README | Quickstart nachgefahren (init → episode new → build → check → deploy), Screenshot-Galerie | | docs/* | Inhaltsverzeichnisse, „Entfallene Schlüssel“, rc.19-Features geprüft; player.md wegen #130 unberührt | | Code-Befunde | Staffel-Feld ungestylt, absoluter Serverpfad in API-Antwort, veralteter „build.sh“-Text im Editor → #136, behoben | Grenzen: drift-Erkennung per grep (berechnete Pfade unsichtbar); Inhaltszeilen werden nicht auf neue Abschnitte geprüft; zentonic26 hat keinen Hellmodus. Issue bleibt offen (Dauer-Checkliste je Release). > 🤖 angelegt von Claude v00 (API/Token holm)
Author
Owner

Housekeeping rc.24 (b9382af): docs-drift.sh 0 Befunde, 11 Screenshots neu erzeugt, 4 geändert (Folgenseite, Panel, Pagination). Doku zu [web] episode_nav und Theme-Block steht in README, docs/configuration.md, docs/theming.md, TEMPLATE.md (#139).

🤖 Claude v00

Housekeeping rc.24 (`b9382af`): `docs-drift.sh` 0 Befunde, 11 Screenshots neu erzeugt, 4 geändert (Folgenseite, Panel, Pagination). Doku zu `[web] episode_nav` und Theme-Block steht in README, docs/configuration.md, docs/theming.md, TEMPLATE.md (#139). > 🤖 Claude v00
Author
Owner

Housekeeping rc.25 (7e880e9): docs-drift.sh 0 Befunde, Screenshots neu erzeugt. Doku zu speaker_pages, aliases und Import-Plan-Prüfung kam mit #140 und #135.

🤖 Claude v00

Housekeeping rc.25 (`7e880e9`): `docs-drift.sh` 0 Befunde, Screenshots neu erzeugt. Doku zu `speaker_pages`, `aliases` und Import-Plan-Prüfung kam mit #140 und #135. > 🤖 Claude v00
Author
Owner

Housekeeping rc.26: Release ohne Code- und Doku-Änderung, nur pemmikan.md. docs-drift.sh geprüft, Screenshots unverändert gültig (Stand rc.25), kein neuer Lauf nötig.

🤖 Claude v00 (API/Token holm)

Housekeeping rc.26: Release ohne Code- und Doku-Änderung, nur `pemmikan.md`. `docs-drift.sh` geprüft, Screenshots unverändert gültig (Stand rc.25), kein neuer Lauf nötig. > 🤖 Claude v00 (API/Token holm)
Author
Owner

Housekeeping rc.27: docs-drift.sh 0 Befunde, docs/player.md um Tempo ergänzt, Screenshots neu.

🤖 Claude v00 (API/Token holm)

Housekeeping rc.27: `docs-drift.sh` 0 Befunde, `docs/player.md` um Tempo ergänzt, Screenshots neu. > 🤖 Claude v00 (API/Token holm)
Author
Owner

Housekeeping rc.29: docs-drift.sh 0 Befunde, docs/player.md um Markdown-Kopieren ergänzt, Screenshots neu.

🤖 Claude v00 (API/Token holm)

Housekeeping rc.29: `docs-drift.sh` 0 Befunde, `docs/player.md` um Markdown-Kopieren ergänzt, Screenshots neu. > 🤖 Claude v00 (API/Token holm)
Author
Owner

Housekeeping rc.27 bis rc.32: docs-drift.sh 0 Befunde, docs/player.md um Mitschrift und Spulen ergänzt, Screenshots neu.

🤖 Claude v00 (API/Token holm)

Housekeeping rc.27 bis rc.32: `docs-drift.sh` 0 Befunde, `docs/player.md` um Mitschrift und Spulen ergänzt, Screenshots neu. > 🤖 Claude v00 (API/Token holm)
Author
Owner

Housekeeping rc.33 bis rc.35: docs-drift.sh 0 Befunde, Screenshots neu.

🤖 Claude v00 (API/Token holm)

Housekeeping rc.33 bis rc.35: `docs-drift.sh` 0 Befunde, Screenshots neu. > 🤖 Claude v00 (API/Token holm)
Author
Owner

Housekeeping rc.36: docs-drift.sh 0 Befunde, Editor-Screenshots neu (editor-edit.png, editor-errors.png), docs/web-editor.md ergänzt.

🤖 Claude v00 (API/Token holm)

Housekeeping rc.36: `docs-drift.sh` 0 Befunde, Editor-Screenshots neu (`editor-edit.png`, `editor-errors.png`), `docs/web-editor.md` ergänzt. > 🤖 Claude v00 (API/Token holm)
Author
Owner

Housekeeping rc.36 bis rc.40: docs-drift.sh 0 Befunde, Screenshots neu.

🤖 Claude v00 (API/Token holm)

Housekeeping rc.36 bis rc.40: `docs-drift.sh` 0 Befunde, Screenshots neu. > 🤖 Claude v00 (API/Token holm)
Author
Owner

Housekeeping rc.41 (Beleg)

  • Commits 17de61d docs: Housekeeping rc.41 und f47b588 docs: Screenshots auf sauberem Stand inkl. #142, gemergt in dev (23de0d0), gepusht.
  • README: zpub import episode in Befehlstabelle, Doku-Tabelle, Quickstart-Hinweis, Selbsttests. docs/player.md mit Inhaltsverzeichnis und Screenshot „Kapitel mit Bild“. docs/import.md-Titel nennt Einzelfolgen. docs/web-editor.md: Alt-Text passt zum Bild.
  • scripts/docs-screenshots.sh: neue Aufnahme player-chapter (Folge 001 bei 0:20, Kapitelbild im Sticky-Player; Abbruch, wenn das Bild nicht sichtbar ist). 15 Bilder in ≈ 1 min, angesehen. Zweiter Lauf auf sauberem Stand (der erste zeigte -dirty in der Fußzeile).
  • docs-drift.sh nach dem Merge: gesamt 0.

🤖 angelegt von Claude claude2604 (API/Token holm)

## Housekeeping rc.41 (Beleg) - Commits 17de61d `docs: Housekeeping rc.41` und f47b588 `docs: Screenshots auf sauberem Stand inkl. #142`, gemergt in dev (23de0d0), gepusht. - README: `zpub import episode` in Befehlstabelle, Doku-Tabelle, Quickstart-Hinweis, Selbsttests. docs/player.md mit Inhaltsverzeichnis und Screenshot „Kapitel mit Bild“. docs/import.md-Titel nennt Einzelfolgen. docs/web-editor.md: Alt-Text passt zum Bild. - `scripts/docs-screenshots.sh`: neue Aufnahme `player-chapter` (Folge 001 bei 0:20, Kapitelbild im Sticky-Player; Abbruch, wenn das Bild nicht sichtbar ist). 15 Bilder in ≈ 1 min, angesehen. Zweiter Lauf auf sauberem Stand (der erste zeigte `-dirty` in der Fußzeile). - `docs-drift.sh` nach dem Merge: gesamt 0. > 🤖 angelegt von Claude claude2604 (API/Token holm)
Author
Owner

Housekeeping rc.42

  • Inhalt rc.42: #142 (Doku docs/player.md „Kopfzeile: Nummer, Tags, Titel“ kam mit dem Fix), #111 (nur Test), Doku-Housekeeping rc.41.
  • Screenshots stammen schon vom Stand mit #142 (f47b588, sauber, ohne -dirty).
  • docs-drift.sh auf dev nach rc.42: gesamt 0. Kein weiterer Doku-Commit nötig.

🤖 angelegt von Claude claude2604 (API/Token holm)

## Housekeeping rc.42 - Inhalt rc.42: #142 (Doku `docs/player.md` „Kopfzeile: Nummer, Tags, Titel“ kam mit dem Fix), #111 (nur Test), Doku-Housekeeping rc.41. - Screenshots stammen schon vom Stand mit #142 (f47b588, sauber, ohne `-dirty`). - `docs-drift.sh` auf dev nach rc.42: gesamt 0. Kein weiterer Doku-Commit nötig. > 🤖 angelegt von Claude claude2604 (API/Token holm)
Author
Owner

Housekeeping rc.43

  • Inhalt rc.43: nur #173 (Check-Werkzeug), keine Doku- oder Oberflächenänderung; Screenshots unverändert gültig.
  • docs-drift.sh auf dev nach rc.43: gesamt 0.

🤖 angelegt von Claude claude2604 (API/Token holm)

## Housekeeping rc.43 - Inhalt rc.43: nur #173 (Check-Werkzeug), keine Doku- oder Oberflächenänderung; Screenshots unverändert gültig. - `docs-drift.sh` auf dev nach rc.43: gesamt 0. > 🤖 angelegt von Claude claude2604 (API/Token holm)
Sign in to join this conversation.
No milestone
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
Zentonic/zentonic-publisher#131
No description provided.