Matthias G
a123e0bca2
Tiptap replaces the plain textarea: bold, italic, subheading, lists and links. Stored as Markdown so API clients keep reading and writing the same field, rendered with react-markdown.
3.6 KiB
Redaktionsleitfaden Logbuch
Diese Datei wird über GET /api/v1/style-guide ausgeliefert. Wer über die API schreibt, liest sie zuerst.
Wofür Logbuch da ist
Logbuch hält fest, was in den Produkten der Firmengruppe passiert ist. Alle zwei Wochen entsteht pro Projekt ein Eintrag über das, was fertig geworden ist.
Es ist kein Änderungsprotokoll für Entwickler und keine Pressemitteilung. Es ist für Kollegen und später Kunden, die wissen wollen, was sich geändert hat, ohne Tickets oder Code zu lesen.
Wer liest
Technische und nicht technische Kollegen aus allen Bereichen. Später Kunden der jeweiligen Produkte. Sie lesen nebenbei, meist weil ihre Anwendung sie auf etwas Neues hingewiesen hat.
Daraus folgt: kein Fachjargon ohne Erklärung, keine Ticketnummern, keine Klassennamen, keine Abkürzungen, die nur im Team bekannt sind.
Aufbau eines Eintrags
- Titel. Sagt, was sich geändert hat. Nicht, dass sich etwas geändert hat.
- Anreißer. Zwei bis drei Sätze, die den Kern nennen und was der Leser davon hat.
- Text. Was war vorher, was ist jetzt, was bleibt zu tun. Meist drei bis sechs Absätze.
Eine Fehlerbehebung darf aus zwei Sätzen bestehen. Eine neue Funktion braucht mehr, weil sie erklärt werden muss.
Titel
Gut:
- "SLA-Uhr zählt Feiertage nicht mehr mit"
- "Spalten per Rechtsklick verwalten"
- "10.000 Tracker auf einer Karte"
Schlecht:
- "Verbesserungen an der Tabelle" (sagt nichts)
- "Wir haben ein spannendes neues Feature gebaut" (Werbung statt Information)
- "MTT-1423 umgesetzt" (Ticketnummer, für Leser bedeutungslos)
Ton
Sachlich und direkt. Aktive Verben. Der Leser wird geduzt oder gar nicht angesprochen, beides ist in Ordnung, aber nicht gemischt.
Verboten: Werbesprache, Superlative, Ausrufezeichen, Emojis, Gedankenstriche. Immer normales Minus. Echte Umlaute, niemals ae, oe, ue.
Nicht behaupten, dass etwas großartig ist. Beschreiben, was es tut, und den Leser selbst urteilen lassen.
Bilder
Zeigen, was sich geändert hat. Kein Firmenlogo, keine Symbolbilder, keine Menschen mit Laptop.
Jedes Bild bekommt einen Alt-Text, der beschreibt, was zu sehen ist. Bei öffentlichen Beiträgen ist der Alt-Text Pflicht, sonst lässt sich der Beitrag nicht veröffentlichen.
Zielgruppe wählen
| Zielgruppe | Wofür |
|---|---|
internal |
Umbauten, Zwischenstände, alles über Kunden, alles Unfertige |
customer |
Was ein Kunde des Produkts wissen soll |
public |
Was auch außerhalb der Firma stehen darf |
Im Zweifel internal. Hochstufen kann ein Mensch beim Freigeben, herunterstufen ist zu spät, wenn es schon draußen war.
Beitragsarten
Die Arten werden im Adminbereich verwaltet und sind über GET /api/v1/post-types abrufbar. Standardmäßig gibt es:
| Schlüssel | Wofür |
|---|---|
feature |
Etwas Neues, das es vorher nicht gab |
improvement |
Etwas Bestehendes wurde besser |
fix |
Ein Fehler ist behoben |
breaking |
Eine Änderung, die Nutzer zum Handeln zwingt |
info |
Hinweis ohne Produktänderung |
Wer veröffentlicht
Nicht der API-Zugang. Ein über die API verfasster Beitrag ist immer ein Entwurf und damit ein Vorschlag. Ein Mensch liest ihn und gibt frei.
Deshalb: lieber einen Entwurf zu viel als einen fehlenden. Aber keine halben Sachen einreichen, die jemand anderes zu Ende schreiben muss.
Auszeichnung
Der Text eines Textblocks wird als Markdown gelesen. Erlaubt sind Absätze, fett, kursiv, Verweise, Aufzählungen, nummerierte Listen und Zwischenüberschriften mit ###. Kein rohes HTML. Sparsam bleiben: Fett hebt hervor, was sonst untergeht, nicht jeden zweiten Halbsatz.