jakubkrehel/better-writing

Schnittstellentexte

Klar und kurz schlägt clever; konsistent schlägt abwechslungsreich. Die beste Fehlermeldung ist die umgestaltete Interaktion, die den Fehler unmöglich macht.

Wie Text dargestellt wird (Großschreibung via text-transform, Abschneiden, intelligente Interpunktion) gehört zu better-typography. Fehlerauszeichnungen und -ankündigungen (aria-invalid, Live-Regionen) gehören zu better-accessibility. Platz für übersetzte Zeichenketten gehört zu better-layout.

Bestehende Stimme erkunden

Bevor Sie schreiben oder überprüfen, lesen Sie den umliegenden Text. Notieren Sie die Terminologie des Produkts, seine Lokalisierungskonventionen sowie etwaige Stimmen- oder Inhaltsstilrichtlinien.

Eine bewusste Markenstimme ist kein Fehler. Weisen Sie nur dann auf eine Abweichung von der einfachen Sprache hin, wenn sie Inkonsistenz, Mehrdeutigkeit, Übersetzungsrisiko oder einen Ton schafft, den die Situation nicht rechtfertigt.

Eine Stimme, flexibler Ton

Das Produkt hat eine Stimme, und der vorhandene Text etabliert sie. Eine lokale Bearbeitung erfindet keine neue. Halten Sie Begriffe konsistent: Wenn es im Menü „Archivieren“ heißt, heißt es im Toast nicht „In Speicher verschieben“. Der Ton passt sich der Situation an:

Kontext	Ton
Erfolg, Onboarding, leere Zustände	Warmherzig, leicht
Routineaktionen, Einstellungen	Neutral, minimal
Fehler, destruktive Bestätigungen	Ruhig, sachlich, kein Spaß
Datenverlust, Sicherheit	Ernsthaft, explizit

Den Leser direkt ansprechen

In Anleitungstexten schreiben Sie „Sie“ und nicht „der Benutzer“. Bei Fehlern lädt „wir“ zu Mehrdeutigkeiten ein und wirkt wie eine Ausrede; bevorzugen Sie daher „Inhalt konnte nicht geladen werden“ anstelle von „Wir haben Probleme, diesen Inhalt zu laden“. Eine etablierte Ich-Perspektive kann in wenig risikobehafteten Texten bleiben, solange sie klar lesbar ist.

Verwenden Sie Possessivformen sparsam: „Favoriten“ ist besser als „Ihre Favoriten“. Halten Sie in einem gesamten Ablauf eine Perspektive durch.

Einfache Wörter statt kluger

Wählen Sie Wörter, die ein müder Leser beim ersten Lesen versteht, und streichen Sie jedes Wort, das keine Arbeit leistet. Keine Redewendungen, keine umgangssprachlichen Ausdrücke, kein Humor, der sich nicht übersetzen lässt.

Vermeiden Sie unnötige Geschlechter: „Abonnenten können Rezepte posten“, nicht „Jeder Abonnent kann seine Rezepte posten“. Passen Sie das Eingabegerät an: „tippen“ auf Touch, „klicken“ mit einem Zeiger, „auswählen“ wenn beides möglich ist.

Setzen Sie niemals einen Satz aus Fragmenten um eine Variable zusammen („Sie haben “ + n + „ neue Nachrichten“), da sich die Wortstellung pro Sprache ändert. Verwenden Sie einen vollständigen Vorlagenstring mit korrekter Pluralisierung.

Verb-zuerst-Schaltflächen

Ein Schaltflächenlabel beginnt mit einem Verb, das die Aktion benennt: „Senden“, „Entwurf speichern“, „Projekt löschen“. Niemals „OK!“, „Los geht's!“ oder ein bloßes „Ja“ und „Nein“ bei einer folgenschweren Aktion.

Eine Bestätigungsschaltfläche wiederholt die Konsequenz, damit der Dialog auch ohne Lesen des Texts beantwortet werden kann. „Dieses Projekt löschen?“ bietet „Projekt löschen“ und „Abbrechen“ an.

Konsistente Flussvokabular

Ein mehrschrittiger Ablauf verwendet durchgehend ein Vokabular: „Loslegen“ zum Eintreten, „Weiter“ oder „Weiter“ (wählen Sie eines aus) zum Fortfahren, „Fertig“ zum Abschließen. Abwechselnde Synonyme lassen Benutzer fragen, ob die Schaltflächen unterschiedliche Funktionen haben.

Links beschreiben ihr Ziel

Der Linktext muss auch ohne Kontext sinnvoll sein, da Screenreader-Benutzer über eine Liste der Seitenlinks navigieren. Schreiben Sie „Lesen Sie die Abrechnungsdokumentation“. „Hier klicken“ verstößt gegen diese und die Geräte-Verb-Regel.

Ein bloßes „Mehr erfahren“ bricht zusammen, sobald zwei auf einer Seite erscheinen. Ergänzen Sie jedes: „Mehr erfahren über Exporte“.

Einheitliche Großschreibung

Wählen Sie Titel- oder Satzfall pro Elementtyp und wenden Sie ihn dann auf jede Instanz dieses Typs an. Satzfall ist die sicherere Standardeinstellung. Er ist ruhiger, hat keine Pro-Wort-Regeln zum Merken und lässt sich sauber lokalisieren. „Änderungen speichern“ neben „Änderungen verwerfen“ wirkt schlampig.

Einstellungen beschreiben den EIN-Zustand

Beschriften Sie einen Kippschalter mit dem, was passiert, wenn er eingeschaltet ist. „Sendebestätigungen senden“ lässt Benutzer den Aus-Zustand ableiten; die Verneinung („Keine Sendebestätigungen senden“) macht den Kippschalter zu einer doppelten Verneinung.

Verlinken Sie direkt zu einer referenzierten Einstellung, anstatt den Pfad dorthin zu beschreiben: ein Link „Benachrichtigungseinstellungen“, nicht „Gehe zu Einstellungen > Benachrichtigungen > E-Mail“.

Fehler sagen, wie man sie behebt, direkt neben der Stelle, an der es kaputt ging

Ein Fehler ist eine Anweisung und gehört neben das fehlgeschlagene Feld:

Schlecht	Gut
Dieses Passwort ist zu kurz	Wählen Sie ein Passwort mit mindestens 8 Zeichen
Ungültiger Name	Verwenden Sie nur Buchstaben für Ihren Namen
Hoppla! Etwas ist schief gelaufen.	Speichern fehlgeschlagen. Überprüfen Sie Ihre Verbindung und versuchen Sie es erneut.

Keine Schuldzuweisungen, kein „Hoppla“, keine Ausrufezeichen. Formulieren Sie Hinweise positiv („Verwenden Sie nur Buchstaben“, nicht „Verwenden Sie keine Zahlen oder Symbole“) und zeigen Sie sie vor dem Fehler, nicht danach. Wenn derselbe Fehler immer wieder auftritt, gestalten Sie die Interaktion um, anstatt den Wortlaut zu ändern.

Leere Zustände weisen nach vorne

Ein leerer Zustand sagt, was dies ist, wie man es füllt und bietet eine klare nächste Aktion an:

<!-- Schlecht: ein Achselzucken -->
<p>Keine Ergebnisse.</p>

<!-- Gut: Orientierung plus nächster Schritt -->
<p class="font-medium">Noch keine Projekte</p>
<p class="text-sm text-zinc-500">Projekte bündeln Ihre Aufgaben und Dateien.</p>
<button class="mt-4">Projekt erstellen</button>

Ein leerer Zustand einer Suche oder eines Filters nennt die Abfrage und bietet einen Ausweg: „Keine Ergebnisse für ‚vierteljährlich'. Filter löschen“. Hinterlegen Sie niemals dauerhafte Informationen in einem leeren Zustand. Er verschwindet, sobald Inhalt vorhanden ist.

Platzhalter sind Beispiele, keine Labels

Ein Platzhalter zeigt das erwartete Format an: [email protected], DD/MM/JJJJ. Er verschwindet bei der Eingabe, daher ist er niemals das einzige Label. Jedes Feld behält ein sichtbares Label.

Berichterstattung

Schweregrad. HOCH führt den Benutzer in die Irre oder verbirgt, wie man sich von einem Fehler erholt. MITTEL bricht die Konsistenz von Stimme, Terminologie oder Großschreibung. NIEDRIG ist eine isolierte stilistische Glättung des Wortlauts.

Verifizierung. Die Quelle allein reicht hier aus. Überprüfen Sie jedes Label gegen die Aktion, die es aufruft, jeden Fehler auf eine angegebene Korrektur und die Terminologie gegen den umgebenden Text. Es ist kein Browser-Check erforderlich.

Format. Gruppieren Sie die Ergebnisse unter dem Prinzip, das jeweils verletzt wird, geordnet nach Schweregrad, eine Zeile pro Ursache, die jeden Ort auflistet, an dem sie auftritt:

Schweregrad	Ort	Vorher	Nachher	Warum

Ort ist pfad/zu/datei:zeile. Warum nennt das Prinzip und die Auswirkung auf den Benutzer.

Beenden Sie mit Blockieren, wenn ein HOCH verbleibt, andernfalls mit Genehmigen, und lassen Sie den Rest in der Tabelle als zu erledigende Arbeit stehen. Genehmigen Sie niemals einen Bereich, den Sie nicht überprüft haben. Wenn nichts zu berichten ist, geben Sie „Keine umsetzbaren Textbefunde“ an und melden Sie die Verifizierung.