Redaktioneller Leitfaden: Hilfethemen in Exponential #

Status: Vorschlag, 18. Oktober 2026. Grundlage: der Plan für das Hilfesystem (Inhaltsmodell, Zugriff, Arbeitsablauf). Die maschinell prüfbaren Regeln prüft seit 6.0.15 ./console exp:help:content check (Hilfe als Inhalt gepflegt).

Dieser Leitfaden gilt für jedes Thema im Themenpool (help-pool). Einen Teil davon prüft der Validator check_help.php; der Rest ist Aufgabe des Reviews. Die Begriffe sind im Glossar festgelegt (siehe Terminologie).

Die Beispiele stammen aus der Administrationsoberfläche von Exponential, sodass sie sich an einer laufenden Installation überprüfen lassen. Eine Site schreibt ihre eigenen Themen in derselben Form.

Verwenden Sie den Produktnamen, den die Leserin oder der Leser auf dem Bildschirm sieht, keinen internen Projekt- oder Codenamen.

1. Thementypen #

Jedes Thema hat genau einen Typ (DITA 1.3). Mischformen gibt es nicht: Ein Thema, das erklärt und anleitet, wird in zwei Themen aufgeteilt, die über related aufeinander verweisen. Ein „FAQ“ ist eine Ansicht (eine help_section mit Verweisen), kein Typ.

Gemeinsame optionale Felder: platform, version_from, version_to, review_date, owner, related, figures. Redakteure füllen platform, version_from, review_date und owner immer aus (Abschnitt 8); das Inhaltsmodell erzwingt sie nur deshalb nicht, damit sich ein Entwurf auch ohne sie speichern lässt.

Welcher Typ wann:

1.1 Vorlage help_concept #

When you edit an object, Exponential creates a draft. The draft is a new
version of the object. Readers of the site do not see it.

When you publish the draft, it becomes the current version. The previous
version stays in the history. You can compare versions and copy an old one
into a new draft.

Drafts you do not publish stay in "My drafts" until you discard them.

1.2 Vorlage help_task #

1. Open the folder in which the article belongs.
2. Select **Article** in the list of content classes.
3. Click **Create here**.
   The edit form opens.
4. Fill in at least the title and the text.
5. Click **Send for publishing**.
   The folder opens again and shows the new article.

1.3 Vorlage help_reference #

1.4 Vorlage help_troubleshooting #

Ein Thema zur Fehlerbehebung geht vom Symptom aus, das die Lesenden sehen. Gibt es eine Fehlermeldung, steht sie wörtlich in condition (in Anführungszeichen, nicht fett: Sie ist Text, keine Beschriftung). Genau danach suchen die Lesenden.

1.5 Zweite Vorlage help_task, für die Anmeldung #

Varianten (Single Sign-on, Anmeldung mit zwei Faktoren) sind eigene Themen, keine Wenn-dann-Verzweigungen in den Schritten. Ein Schritt, der mit „Wenn …“ beginnt, ist erlaubt, wenn er die einzige Verzweigung im Thema ist.

Beschriftungen sind in diesem Leitfaden so zitiert, wie die deutsche Administrationsoberfläche sie zeigt. Bevor ein Thema freigegeben wird, wird jede Beschriftung an der Installation geprüft, die es beschreibt (Abschnitt 4).

2. Minimalismus #

• Die Handlung zuerst. Kein „In diesem Abschnitt erfahren Sie …“, kein „Exponential bietet die bequeme Möglichkeit, …“. Der erste Satz einer Aufgabe ist der erste Schritt oder die Voraussetzung.
• Nur, was die Lesenden für ihre Aufgabe brauchen. Technik (Server, Interna des Cache, Suchindex) kommt in der Hilfe für Besucher und Mitglieder nicht vor.
• Eine Aussage pro Satz. Begründungen kurz und nach der Handlung.
• Nichts Selbstverständliches: kein „Klicken Sie auf Speichern, um zu speichern“.
• Fehler einplanen. Was schiefgehen kann, bekommt ein eigenes Thema zur Fehlerbehebung und einen related-Verweis, keinen Absatz in der Aufgabe.

3. Sprache #

3.1 Anrede #

Sprechen Sie die Lesenden mit Sie an, und zwar in jeder Zielgruppe. Ein Thema für mehrere Zielgruppen verwendet durchgehend dieselbe Form. Für Sprachen mit einer förmlichen und einer vertraulichen Anrede entscheidet jede Installation pro Zielgruppe und hält das in ihrem Glossar fest; die Regel lautet, der Oberfläche zu folgen, die die Lesenden verwenden.

3.2 Einfache Sprache (Besucher, Mitglieder) #

Lesende mit wenig Leseübung (Kinder, Lesende in einer Zweitsprache) brauchen engere Grenzen; eine Installation mit einer solchen Zielgruppe legt sie hier fest, z. B. 15 Wörter pro Satz und 3 Sätze pro Absatz.

3.3 Fachsprache (Redakteure, Administratoren) #

• Sätze mit bis zu 25 Wörtern.
• Die Exponential-Begriffe der Administrationsoberfläche (Objekt, Knoten, Inhaltsklasse, Sektion, Objektzustand, Version, Siteaccess) werden ohne Erklärung verwendet.
• „Klasse“ bedeutet in der Hilfe für Redakteure immer Inhaltsklasse. Hat die Site eine eigene Bedeutung des Wortes, entscheidet das Glossar.

4. Schritte #

Weitere Regeln:

• steps enthält genau eine nummerierte Liste (vom Validator geprüft), keine Unterschritte. Mehr als 9 Schritte: in zwei Aufgaben aufteilen.
• Schritte kommen nicht in context, prereq oder result vor.
• Beschriftungen stammen aus den Übersetzungsdateien der Oberfläche, nicht aus dem Gedächtnis und nicht von einem Bildschirmfoto einer alten Version. Platzhalter werden durch ein Beispiel ersetzt.
• Enthält eine Beschriftung ein Wort, das das Glossar vermeidet, wird sie trotzdem exakt zitiert; im Fließtext gilt der Glossarbegriff. Die Unstimmigkeit geht als Ticket an die Entwickler, nicht in den Hilfetext.
• Unterscheidet sich der Weg je Plattform, bekommt jede Plattform ein eigenes Thema mit einer .variant in der help_id (Abschnitt 7) – nur wenn sich die Schritte unterscheiden, nicht bloß das Aussehen.

5. Hinweise #

IEC/IEEE 82079-1:2019 verlangt Sicherheitshinweise an der Stelle der Gefahr und eine abgestufte Kennzeichnung; die Signalwörter GEFAHR, WARNUNG und VORSICHT (nach ISO 3864-2) beziehen sich auf Gefährdungen von Personen. Websoftware ohne Aktoren verursacht keine körperliche Gefährdung; diese drei Stufen werden deshalb nicht verwendet. Wer sie trotzdem verwendet, entwertet sie für den Fall, in dem es auf sie ankommt, und lässt das Löschen eines Ordners so laut klingen wie einen Stromschlag.

Regeln:

• Dort, wo die Handlung geschieht. Ein Achtungs- oder Datenschutzhinweis steht im Schritt, vor der Handlung, die ihn auslöst – nicht in context, nicht am Ende, nicht in einem Sammelkapitel „Datenschutz“.
• Ein solcher Hinweis ist die einzige Ausnahme von „Der erste Satz ist die Handlung“: Er steht im Schritt vor dem Imperativ.
• Aufbau: Stufe – was passiert – was die Lesenden tun können. Höchstens drei Sätze.
• Ein Hinweis pro Schritt. Wer mehr braucht, hat den Schritt zu groß geschnitten.
• Der Datenschutzhinweis wiederholt nicht die Datenschutzerklärung; er nennt nur, was diese Handlung bewirkt, und verlinkt die Rechtstexte.

Beispiel in einem Schritt:

4. **Attention:** Without "Move to trash" the objects are deleted at once and
   cannot be restored.
   Click **OK**.

6. Abbildungen (help_screenshot) #

Wann überhaupt eine Abbildung: nur wenn ein Bedienelement schwer zu finden ist (Symbol ohne Beschriftung, Menü hinter einem Symbol) oder wenn der Zielzustand visuell geprüft werden muss (ein Diagramm, eine Vorschau). Nicht eine pro Schritt, nicht als Dekoration. Ein Thema muss ohne die Abbildung vollständig sein – die Abbildung ergänzt, sie trägt nie allein eine Information.

Generierte Abbildungen bevorzugen. Wo die Oberfläche durch automatisierte Browser- oder UI-Tests abgedeckt ist, lassen Sie die Tests die echten Bildschirme mit erfundenen Daten zeichnen und die Bilder speichern. Ändert sich die Oberfläche, laufen die Tests erneut, und die Abbildung wird ersetzt. Ein von Hand aufgenommenes Bildschirmfoto veraltet unbemerkt.

Die Sektion einer Abbildung setzt check_help.php --fix anhand der Themen, die auf sie verweisen: öffentlich, sobald eines davon öffentlich ist. Ausgeliefert wird sie erst, wenn sie freigegeben ist, wie das Thema.

Aufnahme (auch für eine von Hand erstellte Abbildung): helles Theme, Standardschriftgröße, die Oberflächensprache des Themas, keine Benachrichtigungen, keine Browser-Erweiterungen im Bild. Hervorheben höchstens mit einem Rahmen um das gemeinte Element, keine Pfeile mit Text.

Keine echten personenbezogenen Daten. Nehmen Sie nur mit Testkonten auf: erfundene Namen, E-Mail-Adressen unter example.org, keine echten Kunden-, Firmen- oder Schulnamen, keine echten Zugangscodes oder Tokens. Wer ein Bildschirmfoto aus einem Produktivsystem braucht, schwärzt zuerst – deckend, nicht weichgezeichnet.

Alternativtext:

• beschreibt, was die Lesenden für ihren Schritt aus der Abbildung brauchen, nicht das Bild als solches: „Bearbeitungsformular mit den Feldern Titel und Text, darunter die Schaltfläche Zur Veröffentlichung schicken.“
• nicht „Bild von …“, „Bildschirmfoto von …“ – das sagt der Screenreader selbst;
• Beschriftungen wörtlich, ohne Formatierung;
• höchstens 150 Zeichen, ein Satz (das Feld fasst 500; die Reserve ist für Diagramme gedacht, deren Aussage sonst verloren ginge). Der Validator meldet mehr bei einer generierten Abbildung als ERROR, sonst als WARNING;
• wiederholt nicht die Bildunterschrift.

Mit jeder Minor-Version prüfen die Redakteure die Abbildungen der betroffenen Bereiche; eine Abbildung, die eine andere Oberfläche zeigt, wird ersetzt, nicht als „ungefähr richtig“ stehen gelassen.

7. help_id #

Die help_id ist der stabile Schlüssel eines Themas: Kontexthilfe, DITA-id, Dateiname im Export.

Schema: area.topic[.variant]:

• nur a-z, 0-9, ein Bindestrich innerhalb eines Teils, ein Punkt zwischen den Teilen;
• mindestens zwei Teile, höchstens 80 Zeichen;
• immer Englisch und ASCII, unabhängig von der Sprache des Textes: Die ID ist ein Schlüssel, kein Titel;
• topic benennt den Gegenstand, nicht den Typ: account.log-in, nicht account.task-log-in;
• variant nur für Plattform- oder Rollenvarianten: account.log-in.sso, media.upload.mobile.

Bereiche (Beispiel für die Administration von Exponential; eine Site ergänzt eigene):

Ein neuer Bereich wird hier eingetragen, bevor das erste Thema ihn verwendet.

Eine help_id wird nie umbenannt und nie wiederverwendet. Clients rufen sie auf; eine geänderte ID ist ein toter Link für jede bereits verwendete Client-Version. Ändert sich der Gegenstand eines Themas so stark, dass die ID nicht mehr passt, wird ein neues Thema mit einer neuen ID angelegt; das alte bekommt version_to und einen Link auf das neue. Ein Tippfehler in einer freigegebenen ID bleibt.

8. Felder #

shortdesc #

• Ein Satz, mit Punkt, höchstens 250 Zeichen; anzustreben sind weniger als 150.
• Sagt, was die Lesenden danach tun können oder wissen. Aufgabe: Zweck der Handlung; Konzept: die Kernaussage; Referenz: was die Tabelle enthält; Fehlerbehebung: Symptom und Richtung der Lösung.
• Wiederholt nicht den Titel, beginnt nicht mit „Dieses Thema …“.
• Kein Markup, kein Link, keine fetten Beschriftungen – die shortdesc ist zugleich Linktext, Suchtreffer und Vorschau.

Zielgruppe und Sichtbarkeit #

Daraus folgt:

• Ein Thema für Besucher und Redakteure ist öffentlich. Was nur Redakteure wissen sollen, gehört in ein eigenes internes Thema.
• Lesende mit einer weiter gefassten Rolle lesen auch die Themen der engeren Zielgruppen; ein Thema für Redakteure verlinkt deshalb auf das Thema für Mitglieder, statt es zu wiederholen.
• Die Sektion setzt check_help.php --fix, nicht die Redakteure von Hand.

Zustände (help_status) #

Jede Änderung an einem freigegebenen Thema, selbst ein Tippfehler: Jemand mit der Freigaberolle setzt es auf Review zurück, der Redakteur ändert es, dann wird es erneut freigegeben.

Version und Prüfdatum #

Terminologie #

Das Glossar entscheidet: help_glossary_entry im Ordner „Glossar“ (help-pool-glossary). Jeder Eintrag nennt den Begriff, die zu vermeidenden Synonyme und den Grund. Grundsatz: Das Wort, das die Oberfläche zeigt, hat Vorrang vor dem Wort aus Spezifikationen, Tickets oder dem Code. Der Validator meldet die abgelehnte Form.

Typische Entscheidungen für Exponential:

Ein Begriff, der im Glossar fehlt, wird ergänzt, bevor er in mehr als einem Thema vorkommt.

Siehe auch #

• Plan für das Hilfesystem
• Glossar