Plan: Benutzerhandbücher und Hilfe, gepflegt in Exponential #

Status: Vorschlag, 18. Oktober 2026; Phase 1 (Klassen, Baum, Sektionen, Zustände, Rollen, Validator, Web- und Kontexthilfe in der Hilfe der Administration) umgesetzt in 6.0.15, siehe Hilfe als Inhalt gepflegt; ab 20. Oktober 2026 auch der DITA-Export (Auslieferungsweg 3 und der Export für Weg 4), die als Dateiobjekte gespeicherten und bei der Freigabe neu gebauten E-Books (Auslieferungsweg 3) und die Liste der Topics mit überfälliger Prüfung im Dashboard (Phase 7), siehe den Hinweis zur Aktualisierung; ab 25. Oktober 2026 der Rest: die Regel, dass der Autor nicht freigibt, der Prüfablauf auf der Seite des Themas, veröffentlichte help_ids nie umbenannt oder wiederverwendet, die übrigen maschinell prüfbaren Regeln des Styleguides, „War das hilfreich?“ (Phase 7), Kontexthilfe für Clients mit Token (Auslieferungsweg 2), epubcheck und Ace, wo die Site sie hat (Weg 3), der regelmäßige DITA-Export nach git (Weg 4) und die Templates der öffentlichen Site (Weg 1, Extension exphelpsite), siehe den Hinweis zur Aktualisierung. Was ausgelassen ist und warum: Abgleich mit den Spezifikationen. Begleitseite: der Styleguide für die Hilfe.

Idee #

Die Hilfe einer Site ist Inhalt dieser Site. Sie wird in der Administrationsoberfläche von Exponential geschrieben, geprüft und freigegeben wie jeder andere Inhalt und von dort an drei Stellen ausgeliefert: an die öffentliche Site, an einen JSON-Endpunkt für Kontexthilfe in anderen Clients und in E-Books (EPUB/PDF). Es gibt kein separates Dokumentationswerkzeug und keine zweite Kopie des Textes.

Der Plan beschreibt das Inhaltsmodell, die Zugriffsregeln, den Workflow, die Auslieferungswege und die Prüfungen. Er ist unabhängig von einer bestimmten Site: Zielgruppen, Produktnamen und Bereiche in den Beispielen sind Platzhalter, die jede Installation selbst füllt.

Entscheidungen #

Zielgruppen #

Die Zielgruppen sind eine konfigurierbare Liste. Eine typische Installation:

Dokumentation für Betrieb und IT (Installation, Bereitstellung, Servereinrichtung) bleibt im Repository neben dem Code, nicht im CMS: Sie muss lesbar sein, wenn das CMS nicht läuft.

Der Standard: was DITA hier bedeutet #

• Jedes Topic hat genau einen Typ: concept, task, reference, troubleshooting. Es gibt keine Mischformen; eine „FAQ“ ist eine Ansicht, kein Typ.
• Ein Handbuch ist eine Bookmap; Kapitel sind topichead/chapter mit topicrefs.
• Zielgruppe, Plattform und Version sind DITA-Filterattribute (audience, platform, rev/props); eine DITAVAL-Datei pro Handbuch erzeugt die Ausgabe für eine Zielgruppe.
• Jedes Topic hat eine shortdesc (einen Satz). Sie ist zugleich Linktext, Suchtreffer und Vorschau.
• 82079-1 verlangt Sicherheits- und Datenschutzhinweise dort, wo die Handlung stattfindet (im Schritt, nicht in einem Anhang), Voraussetzungen vor den Schritten und ein Ergebnis danach.

Inhaltsklassen (Präfix help_) #

Weder das alte documentation_page noch article: Die Hilfe braucht Felder, die diese Klassen nicht haben, und sie darf nicht mit den redaktionellen Inhalten der Site vermischt werden. Zwei harte Bedingungen:

• Die Hilfe ist nie eine Quelle für suchbasierte KI-Antworten (RAG), es sei denn, das ist ausdrücklich gewollt. Sonst wird die Hilfe zu einer zitierfähigen Quelle für Fragen, für deren Beantwortung sie nie geschrieben wurde.
• Die Hilfe liegt nicht unter dem regulären Inhaltsbaum der Site, damit sie nicht in Menüs, Listen und Feeds der Site auftaucht.

Struktur (Maps) #

Topics (im Pool) #

Felder, die alle vier Typen gemeinsam haben:

Pro Typ:

Bausteine #

Die Terminologie driftet, sobald mehr als eine Person schreibt. Das Glossar entscheidet jedes Paar konkurrierender Wörter; der Validator meldet die abgelehnte Form.

Auswahloptionen werden immer nur angehängt. ezselection speichert die Position einer Option. Wird die Liste umsortiert, erhält jedes Topic stillschweigend eine andere Zielgruppe und über den Validator eine andere Sektion.

Status #

Als Zustandsgruppe help_status („Entwurf“ → „Prüfung“ → „Freigegeben“), nicht als Feld: Objektzustände können als Einschränkungen von Rollen verwendet werden. Nur „Freigegeben“ wird ausgeliefert (Web, Endpunkt, E-Book).

Der Zustand gehört zum Objekt, nicht zur Version. Wer ein freigegebenes Topic bearbeitet und veröffentlicht, liefert die Änderung sofort aus. Deshalb darf die Redaktionsrolle nur Topics im Zustand „Entwurf“ oder „Prüfung“ bearbeiten (siehe „Berechtigungen“).

Zugriff über Sektionen #

Zwei Sektionen, help_public und help_internal. Die Rolle Anonymous erhält content/read nur mit einer Einschränkung auf help_public und den Zustand „Freigegeben“ – eine Richtlinie mit beiden Einschränkungen, nicht zwei Richtlinien (zwei würden Lesezugriff bei jeder der beiden Bedingungen gewähren). Ein Topic ist öffentlich, wenn seine audience eine öffentliche Zielgruppe enthält (im Beispiel oben die Besucher); andernfalls ist es intern, und ein Topic ohne Zielgruppe ist als sichere Rückfallebene intern.

Die Sektion setzt das Validator-Skript anhand von audience, niemals von Hand. Von Hand gesetzt, driftet sie, sobald jemand die Zielgruppe ändert, und ein internes Topic landet im offenen Web.

Die Sektion wird nur am Objekt gesetzt, nie am Teilbaum: Ein Handbuch ist ein Container, und eine Zuweisung an den Teilbaum würde die Entscheidungen des Validators bei jedem Lauf wieder rückgängig machen. Wird ein Objekt in der Administrationsoberfläche verschoben, erhält es die Sektion seines neuen übergeordneten Knotens; führen Sie den Validator danach erneut aus.

Das Glossar ist immer intern, unabhängig von seiner Zielgruppe: Es ist ein redaktionelles Werkzeug, und seine Anmerkungen sind nicht für anonyme Leser bestimmt.

Baum #

Help                          (folder, remote_id help-root)
├── Topic pool                (folder, remote_id help-pool)
│   ├── Concepts / Tasks / Reference / Troubleshooting
│   ├── Figures               (help_screenshot)
│   └── Glossary              (help_glossary_entry)
├── Manuals                   (folder, remote_id help-manuals)
│   ├── Manual for members
│   ├── Manual for editors
│   └── Manual for administrators
└── E-books                   (folder, remote_id help-ebooks)

Alles wird über die remote_id gefunden, nie über eine Knoten-ID in einer INI-Datei. Knoten-, Sektions- und Zustands-IDs unterscheiden sich zwischen Installationen und werden zur Laufzeit aufgelöst.

Berechtigungen #

Wer ein Topic geschrieben hat, ist nicht die Person, die es freigibt. Eine Änderung an einem freigegebenen Topic, selbst ein Tippfehler: Jemand mit „Hilfe-Freigabe“ setzt es zurück auf „Prüfung“, die Redaktion ändert es, dann wird es erneut freigegeben.

Auslieferungswege #

1. Web (öffentlich): Templates full/help_*.tpl und line/help_*.tpl im Design der Site. Relationen (topicrefs, related, figures) werden nur angezeigt, wenn der Leser das Ziel lesen darf; über den Zugriff entscheiden allein die Berechtigungen von Exponential, die Templates filtern nicht nach Zielgruppe.
2. Kontexthilfe: ein JSON-Endpunkt /<module>/help/<help_id> und /<module>/help/manual/<remote_id>, Inhalt in Markdown, ETag. Öffentliche Topics ohne Anmeldung; interne Topics mit einem Token und einer passenden Rolle. Eine mobile App oder ein JavaScript-Frontend öffnet die Hilfe über die help_id an der richtigen Stelle.
3. E-Book: CLI export_manual.php -s <admin siteaccess> --manual=<remote_id> --format=dita|epub|pdf [--dry-run]. Exponential → DITA-Bookmap + DITAVAL → DITA-OT 4.x → EPUB3/PDF → epubcheck + Ace by DAISY → gespeichert als Dateiobjekt unter „E-books“ (Sektion entsprechend der Zielgruppe).
4. Verlauf: Der DITA-Export läuft regelmäßig in ein eigenes Git-Repository. Der Inhalt lebt im CMS, der Änderungsverlauf landet trotzdem in Git.

CLI-Skripte #

Alle Skripte:

• nehmen -s <siteaccess> als Pflichtoption und geben Siteaccess und Datenbank aus, bevor sie beginnen (ein Verzeichnisbaum kann mehrere Installationen mit verschiedenen Datenbanken bedienen);
• folgen startup() → getOptions() → initialize() und rufen initialize() genau einmal auf;
• unterstützen --dry-run;
• sind idempotent: Ein zweiter Lauf meldet „No change.“ – das ist der Abnahmetest.

Zwei Tatsachen des Kernels, mit denen die Skripte umgehen müssen:

• Der erste Zustand einer neuen Zustandsgruppe wird jedem vorhandenen Objekt der Installation zugewiesen. Das ist harmlos, solange nur Hilfe-Richtlinien die Gruppe auswerten.
• ezcobj_state_language.description hat in MySQL keinen Standardwert. Ohne Beschreibung schlägt das INSERT unter STRICT_TRANS_TABLES fehl; das Skript muss eine setzen.

Prüfungen #

• Klassenskript idempotent (zweiter Lauf: keine Änderung).
• Hilfe nie in einer Quellenliste für RAG/KI, nie unter dem Inhaltsbaum der Site.
• Anonymous liest nur help_public + „Freigegeben“ (prüfbar mit einer Untersuchung der Rolle und mit einer anonymen Anfrage nach einem internen Topic, die keinen Inhalt liefern darf).
• Validator (check_help.php):
  • task ohne genau eine nummerierte Liste;
  • Screenshot ohne Alternativtext, Alternativtext länger als 150 Zeichen;
  • Topic ohne shortdesc, shortdesc länger als ein Satz;
  • ungültige oder doppelte help_id;
  • ein Wort, das das Glossar ablehnt (fett gesetzter Text ist eine zitierte Beschriftung der Oberfläche und wird nicht geprüft);
  • Überprüfungsdatum in der Vergangenheit;
  • Sektion, die nicht zur Zielgruppe passt.
• Clients, die die Hilfe über die help_id aufrufen, führen eine Liste der IDs, die sie verwenden; ein Test prüft, dass jede davon im Export vorhanden ist.

Phasen #

1. Grundlagen: Klassen, Baum, Sektionen, Zustände, Rollen.
2. Redaktioneller Styleguide (help-style-guide.md) und Glossar.
3. Validator.
4. Web-Templates und Endpunkt für die Kontexthilfe.
5. E-Book-Export mit epubcheck und Ace.
6. Inhalte: zuerst, was Besucher brauchen, dann Mitglieder, Redakteure, Administratoren.
7. Pflege: eine Liste veralteter Topics (Überprüfungsdatum überschritten) im Dashboard der Administration, „War das hilfreich?“ bei jedem Topic.

Siehe auch #

• Styleguide für die Hilfe
• Standards für die Hilfe: was die Hilfe aus DITA 1.3, IEC/IEEE 82079-1, ISO/IEC/IEEE 26514, ISO 3864-2, EPUB Accessibility 1.1 und WCAG 2.2 AA übernimmt
• Die Hilfeklassen als Paket
• Hilfe als Inhalt gepflegt: was von diesem Plan umgesetzt, in Arbeit oder ausgelassen ist
• Sektionen
• Objektzustände
• Rollen und Richtlinien