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.
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# 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
|
|
|
|
1. **Titel.** Sagt, was sich geändert hat. Nicht, dass sich etwas geändert hat.
|
|
2. **Anreißer.** Zwei bis drei Sätze, die den Kern nennen und was der Leser davon hat.
|
|
3. **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.
|