Matthias Giesselmann
b90ff252d1
Public archive with sidebar navigation, project pages, month archive, search and entry pages with image blocks. Admin area for brands, projects, post types, users, api clients, media and the entry editor with drag and drop images, preview per audience, scheduling and publish checks. Read and write API with bearer tokens, audience scoping, idempotent creation, OpenAPI document and editorial guide. Magic link login with configurable allowed domains, whole app behind the session gate. 456 tests including design rule checks.
80 lines
3.3 KiB
Markdown
80 lines
3.3 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.
|