Eigenständiger Bereich des Corporate Design Manuals für technische Dokumente: Anleitungen, Handbücher, Release Notes, Fachartikel und vergleichbare Inhalte. Diese Dokumente werden nicht gelesen, sondern benutzt — meist unter Zeitdruck, oft parallel zur Arbeit in der Software. Gestaltung ist hier eine Funktion, keine Dekoration.
0. Geltungsbereich und Abgrenzung
Dieser Bereich ergänzt zwei bestehende, bereits freigegebene Dokumente und dupliziert keines:
| Dokument | Regelt | Verhältnis zu diesem Bereich |
|---|---|---|
cd-styleguide.md |
Farben, Typografie, Logo, Claim, Blocktypen, PDF-Layout — für alle externen Publikationen | Dieser Bereich erbt die dort definierte Farbpalette/Typografie vollständig (siehe §14 Konsistenzprüfung) und erweitert sie um zwei neue Blocktypen (prereq/tip, siehe cd-styleguide.md §9 Rev. 6), die spezifisch für technische Dokumente gebraucht werden |
editorial-guideline.md |
Sprache, Tonalität, Redaktionsworkflow, Terminologie-Prozess, Versionierungs-Pflichtfelder — wie Inhalte entstehen | Dieser Bereich regelt wie sie aussehen und strukturiert sind (Layout, Gliederung, Handlungsanweisungs-Darstellung, Screenshot-Vorgaben) — keine Sprach-/Tonalitätsregeln, keine Workflow-Duplikation |
Markenkern für technische Dokumente (CEO-Freigabe, LIR-2890 §1):
- Sicher und professionell nach deutschem Standard — Nachvollziehbarkeit, Versionsklarheit, Vollständigkeit.
- Einfach und maximal unterstützend — Struktur ermöglicht das Finden, nicht nur das Lesen.
Besonderheit: Medienübergreifende Konsistenz (Webseite, PDF-Download, Ausdruck, ggf. In-App- Hilfe) ist zwingend — keine formatgebundenen Sonderregeln, siehe §13.
1. Zuständigkeit und Freigabeweg
Aus LIR-2890 §2.1/§2.3, hier als Arbeitsgrundlage für diesen Bereich übernommen:
| Bereich | Zuständig | Freigabe |
|---|---|---|
| Farben, Typografie, Layouts, Titelseiten-Struktur | MarketingLead | gestalterisch |
| Dokumentarten, Gliederungshierarchien, Blocktyp-Verwendung, Terminologie, Versionierungskonzept | Technical Writer | funktional |
| Schnittstelle: Hinweisboxen, Tabellen-/Dokumentkopf-Layout | beide — MarketingLead gibt visuelle Umsetzung frei, TR die funktionale Eignung | gemeinsam |
Konflikte zwischen Gestaltung und Funktionalität eskaliert der Technical Writer an den CEO (LIR-2890 §2.3). Rev. 1 war der gestalterische Entwurf von MarketingLead; mit Rev. 2 hat Technical Writer die in §19 gelisteten Schnittstellen-Abschnitte funktional geprüft, teils mit Korrekturen bestätigt (siehe Änderungshistorie). Technical Writer und MarketingLead sind weiterhin eingeladen, Dokumentarten und Vorgaben zu ergänzen (LIR-2890 §8) — dieses Dokument bleibt ein Rahmen, keine abgeschlossene Spezifikation.
2. Dokumentarten
Ausgangsliste aus LIR-2890 §6, um zwei aus der bestehenden Repo-Praxis
bereits sichtbare Typen ergänzt (Vorschlag MarketingLead, TR-bestätigt Rev. 2: beide passen
zur bestehenden editorial-guideline.md §4-Typologie — API-/Integrationsdoku deckt sich mit dem
dort bereits definierten Typ „Integrationsdoku (extern)“, Migrationsleitfaden ist eine sinnvolle
Ergänzung ohne bestehende Entsprechung. Keine weiteren Dokumentarten-Lücken aus TR-Sicht erkennbar):
| Dokumentart | Bereits etabliert unter | Layout-Basis |
|---|---|---|
| Software-Handbuch / Benutzerdokumentation | handbook/ |
Web + PDF, siehe §5–§9 |
| Schritt-für-Schritt-Anleitungen und Schnellstart | handbook/tutorials/ |
Web + PDF, Sonderfall Handlungsanweisungen (§8) |
| Release Notes und Änderungshistorie | release-notes/ (geplant) |
Web + PDF, Kurzform-Layout (§15 Muster B) |
| Fachartikel für den Blog | — (Blog-Redaktionsplan siehe docs/konzept_blog_redaktionsplan_lir-2884.md) |
primär Web, PDF optional |
| FAQ und Troubleshooting | help-center/ |
Web-first, „Antwort vor Kontext“ (Editorial Guideline §4), PDF nachrangig |
| Onboarding-Material und Schulungsunterlagen | — (noch keine Publikation) | Web + PDF, ggf. Foliensatz-Sonderfall (offener Punkt, §16) |
| Technische Datenblätter und Systemvoraussetzungen | overview/ (product-status-features-user-rights) |
PDF-first, Tabellen-lastig (§10) |
| Hilfetexte innerhalb der Anwendung (In-App-Hilfe) | — (noch keine Publikation) | Web-only, kein PDF-Äquivalent nötig (Kurzform, siehe §13) |
| Neu (TR-bestätigt Rev. 2): API-/Integrationsdokumentation | integration/ (bei Bedarf, siehe Editorial Guideline §4) |
Web + PDF, Code-Block-lastig (§11) |
| Neu (TR-bestätigt Rev. 2): Migrationsleitfaden (Versionswechsel/Breaking Changes) | — (noch keine Publikation) | wie Release Notes, aber mit prereq-Blöcken pro Schritt (§7) |
3. Werkzeugkette — Single Source Publishing
Bestätigt und erweitert aus cd-styleguide.md §11 und LIR-2890 §2.4:
- Inhalt: Markdown (Standardfall, siehe bestehende
handbook//help-center/-Dateien) oder.cjs-Module mitdoc.sections-Array (Sonderfall: Tabellen-/datengetriebene Dokumente wieoverview/product-status-features-user-rights.cjs). - Web-Ausgabe: Dokumentationsserver (lirai-www-Integration, entschieden in LIR-2868/LIR-2863).
- PDF-Ausgabe:
templates/techdoc-template.js(Node.js/pdfkit). - Konsequenz: Alle in diesem Bereich getroffenen Vorgaben müssen medienübergreifend funktionieren. Wo ein Medium eine Fähigkeit hat, die ein anderes nicht hat (z. B. interaktive Sprungmarken im Web, keine Entsprechung im Ausdruck), wird das Äquivalent für das andere Medium explizit benannt (siehe §13).
4. Dokumentkopf
Gestaltung (MarketingLead, freigegeben):
- Position: erste sichtbare Zeile des Dokuments, vor der H1-Überschrift — bereits etabliertes
Muster in allen bestehenden Dateien des Redaktionsbereichs (siehe z. B.
cd-styleguide.mdZeile 3,handbook/tutorials/01-erste-schritte.mdZeile 3). - Web-Darstellung: einzeilige Metazeile in „Text gedämpft“ (
#6b7280), 9 pt-Äquivalent, Felder durch|getrennt (bestehende Konvention, unverändert). - PDF-Darstellung: Metadatenblock auf der Titelseite (Teal-hell-Fläche, siehe
cd-styleguide.md§5 Punkt 5) — bereits implementiert intechdoc-template.js, keine Änderung nötig. - Bei Kapiteldokumenten ohne eigene Titelseite (z. B. einzelne Handbuch-Kapitel, die als Teil
eines größeren PDFs gerendert werden): Kopfzeile der Inhaltsseite, siehe
cd-styleguide.md§6.
Pflichtfelder (Technical Writer, bestehend + TR-bestätigte Erweiterung, Rev. 2 umgesetzt):
Editorial Guideline §6 definierte bereits Status | Autor | Quelle-Ticket | Stand (Rev.). Für
technische Dokumente im Sinne von LIR-2890 — die benutzt statt gelesen
werden und deren Gültigkeit an einen Softwarestand gebunden ist — hat MarketingLead zwei
zusätzliche Felder vorgeschlagen. TR hat den Vorschlag geprüft, für sinnvoll befunden und in
editorial-guideline.md §6 (Rev. 4) sowie im PDF-Mirror editorial-guideline.cjs umgesetzt:
- Softwarestand: auf welche Produktversion/welchen Release sich das Dokument bezieht. Pflichtfeld bei Nutzerhandbuch-Kapiteln und Release Notes, optional bei Hilfe-Center-Artikeln/ Blog-Fachartikeln, entfällt bei Prozessdokumenten wie der Editorial Guideline selbst.
- Gültigkeit: Datum oder Release, bis zu dem das Dokument als aktuell gilt (verwandt mit, aber nicht identisch zu Editorial Guideline §5 „Periodische Aktualitätsprüfung“ — Gültigkeit ist eine im Dokument sichtbare Aussage, die Aktualitätsprüfung ist der dahinterliegende Prozess). Optional für alle Dokumenttypen.
Format wie vorgeschlagen, angehängt an die bestehende Kopfzeile (kein zweiter, konkurrierender
Block): Status: … | Autor: … | Quelle-Ticket: … | Stand: … | Softwarestand: v2026.7 | Gültigkeit: bis nächstes Major-Release.
5. Gliederung und Navigation
Überschriftenhierarchie (gestalterisch, aus cd-styleguide.md §8 übernommen, hier auf
Web-Markdown gemappt):
| Markdown | Verwendung | Web (lirai-www) | PDF (techdoc-template.js) |
|---|---|---|---|
# (H1) |
Dokumenttitel, genau einmal pro Dokument | 25 pt entsprechend Titelseiten-Titel | Titelseiten-Titel |
## (H2) |
Hauptabschnitt | 14 pt Bold Navy | h2-Blocktyp |
### (H3) |
Unterabschnitt | 11 pt Bold Navy Outline | h3-Blocktyp |
#### |
nicht verwenden | — | kein Blocktyp definiert |
Maximale Verschachtelungstiefe: zwei Ebenen unterhalb des Dokumenttitels (H2 → H3). Ein
Dokument, das eine vierte Ebene „braucht“, ist ein Signal, es in mehrere Dokumente zu splitten
(passt zur „Finden statt Suchen“-Philosophie, Editorial Guideline §3) — kein Blocktyp für ####
vorgesehen.
Nummerierung: Abschnittsnummern (## 1. …, ## 2. …) für Referenzdokumente mit vielen
Abschnitten (CD-Manual, Styleguide, Datenblätter) — bereits etabliertes Muster in diesem Dokument
und in cd-styleguide.md. Für kurze Handbuch-Kapitel/Tutorials/Hilfe-Center-Artikel keine
Nummerierung (Muster aus handbook/tutorials/01-erste-schritte.md: „Schritt 1“, „Schritt 2“ statt
Abschnittsnummern — die Schrittnummer ist hier die Navigation).
Inhaltsverzeichnis:
- Web: automatisch aus H2/H3 generiert (Aufgabe des Dokumentationsservers, siehe LIR-2868/LIR-2863 — kein manuell gepflegtes Verzeichnis im Markdown).
- PDF: bei Dokumenten über ca. 5 Seiten (Datenblätter, CD-Manual, Styleguide) — noch nicht in
techdoc-template.jsimplementiert, Spezifikation folgt Prinzip voncd-styleguide.md§9/§10 (Spec-only bis zum ersten konkreten Bedarf); kurze Dokumente (Tutorials, Hilfe-Center-Artikel, Release Notes) benötigen kein PDF-Inhaltsverzeichnis.
Querverweise und Sprungmarken: Web nutzt Standard-Markdown-Anker ([Text](#abschnitt) bzw.
[Text](anderes-dokument.md#abschnitt)); PDF-Äquivalent (klickbare interne Links) ist eine
pdfkit-Fähigkeit, aktuell in techdoc-template.js nicht genutzt — bis zur Implementierung gilt
die Textform „siehe Abschnitt N“ als Äquivalent (Medienübergreifende-Konsistenz-Pflicht aus §0/§13:
jeder Web-Querverweis braucht ein Druck-taugliches Äquivalent, nicht zwingend denselben
Mechanismus).
6. Textgestaltung
- Zeilenlänge: kein hartes Markdown-Umbruchlimit (Web-Rendering übernimmt Reflow); Richtwert für gut lesbare Absätze: 80–120 Zeichen pro Satz im Fließtext, keine Bandwurmsätze — deckt sich mit Editorial Guideline §3 „klar, handlungsorientiert“.
- Absatzabstände: ein Leerzeilenabsatz zwischen Absätzen (Standard-Markdown), keine manuellen
<br>-Umbrüche innerhalb eines Absatzes. - Listen:
ulfür unsortierte Aufzählungen (Teal-Punkt, siehecd-styleguide.md§9), nummerierte Listen (1.,2., …) nur für tatsächliche Reihenfolgen (Schritt-für-Schritt, Rangfolgen) — nicht als Ersatz fürulbei unsortierten Punkten. - Maximale Verschachtelungstiefe von Listen: zwei Ebenen (Liste → Unterliste). Tiefere Verschachtelung ist ein Signal für eine Tabelle oder einen eigenen Unterabschnitt.
- Tabellen: siehe §10 (Screenshots/Abbildungen) und
cd-styleguide.md§10 — Kopfzeile Navy-Hintergrund, alternierende Zeilen. Faustregel: Tabelle ab 3 Spalten/3 Zeilen strukturierter Daten; für einfache Zwei-Werte-Listen (Label/Wert) reicht eine Markdown-Liste.
7. Handlungsanweisungen
Einheitliche Auszeichnung für Schritte, Eingaben, Schaltflächen, Menüpfade und Tastenkombinationen — Vorschlag MarketingLead, TR-Konvention bestätigt Rev. 2 (mit einer Korrektur, siehe unten):
| Element | Auszeichnung | Beispiel |
|---|---|---|
| Schrittüberschrift | ### Schritt N: <Imperativ> |
### Schritt 1: Dokument hochladen |
| Schaltfläche/Button | Fettschrift, Wortlaut exakt wie im UI | Klicken Sie auf „Problem melden“ |
| Menüpfad | Fettschrift, Pfeil als Trenner | Einstellungen → Team → Einladen |
| Eingabefeld-/Feldname | Code-Auszeichnung (siehe §11) |
Tragen Sie den Wert in Rechnungsnummer ein |
| Tastenkombination | Code-Auszeichnung, Pluszeichen als Trenner |
Strg + S |
| Status-/Zustandswert (FSM) | Code-Auszeichnung, exakter Enum-Wert |
Status wechselt zu approved |
TR-Korrektur zum Beispielwert: Der ursprüngliche Entwurf zeigte reviewed als Beispiel — dieser
Wert existiert nicht im Invoice-FSM (packages/shared/src/domain.ts INVOICE_STATUSES: processing, inbox, todiscuss, approved, paid_debit, paid, deleted; reviewed/extracted sind keine
Dokument-Status, sondern nur Feld-Status, FIELD_STATUSES). Ersetzt durch den realen Wert
approved, damit dieses CD-Manual selbst nicht die gleiche Verwechslung vorführt, die die
Fachprüfung in LIR-2896 bei Tutorial 1 bereits fand — siehe §15 Muster A.
Schrittüberschrift-Format — Klarstellung Rev. 2: 03-email-import.md und die bisherige
00-template.md-Fassung nutzten abweichend ### N. <Imperativ> (ohne das Wort „Schritt“), während
01-erste-schritte.md/02-rechnung-freigeben.md bereits ### Schritt N: <Imperativ> verwenden. TR
bestätigt ### Schritt N: <Imperativ> als verbindliche Konvention (bessere Orientierung im Sinne
von „Finden statt Suchen“) und hat 00-template.md entsprechend angeglichen; die Angleichung von
03-email-import.md erfolgt im Rahmen seiner bereits laufenden Korrektur aus
LIR-2896, nicht als separate Änderung in diesem Ticket.
Größtenteils bereits konsistent in der bestehenden Tutorial-Serie umgesetzt (siehe Positivbeispiel
§15 Muster A) — dieser Abschnitt macht die bisher implizite Konvention explizit und verbindlich, ergänzt um
prereq-Blöcke (siehe cd-styleguide.md §9 Rev. 6) für den „Voraussetzungen“-Abschnitt, den
00-template.md bereits als Freitext-Abschnitt kennt.
8. Hinweisboxen
Vier Typen, wie in LIR-2890 gefordert. Farb-/Typografie-Spezifikation:
siehe cd-styleguide.md §7 (Farben) und §9 (Blocktypen, Rev. 6) — hier nicht dupliziert, nur die
Verwendungsregel (wann welcher Typ; funktionale Eignung TR-bestätigt Rev. 2, Abgrenzung
prereq vs. note vs. Editorial-Guideline-Freitext-Voraussetzungen im Tutorial-Template ist
trennscharf genug für den Redaktionsalltag):
| Typ | Blocktyp | Wann verwenden | Wann nicht |
|---|---|---|---|
| Hinweis | note |
neutrale Zusatzinformation, kein Handlungsdruck | nicht für Warnungen oder Voraussetzungen zweckentfremden |
| Voraussetzung | prereq (neu) |
was vor diesem Abschnitt/Schritt gegeben sein muss (Rolle, Berechtigung, Zustand) | nicht für optionale Tipps |
| Tipp | tip (neu) |
optionaler Zusatznutzen, Zeitersparnis, Komfortfunktion | nicht für notwendige Schritte — die gehören in die Haupt-Anleitung |
| Warnung | warning |
Handlung erforderlich oder Risiko (z. B. Datenverlust, irreversible Aktion) | nicht für gewöhnliche Hinweise — sparsam einsetzen, sonst verliert die Box ihre Signalwirkung |
Zurückhaltender Einsatz (CEO-Vorgabe, LIR-2890 Deliverables Punkt 3): maximal eine Hinweisbox pro Schritt/Unterabschnitt als Richtwert; mehrere aufeinanderfolgende Boxen im selben Abschnitt sind ein Signal, den Fließtext zu überarbeiten statt weitere Boxen zu addieren.
9. Screenshots und Abbildungen
Bildausschnitt: Ausschnitt auf den relevanten UI-Bereich beschränken (kein Vollbild-Screenshot der ganzen Anwendung, außer beim allerersten Einstiegsschritt eines Tutorials — siehe Positivbeispiel §15 Muster A, Schritt 1).
Auflösung: Referenzbreite entspricht CONTENT_WIDTH aus techdoc-template.js (Web skaliert
das PDF-taugliche Bild responsiv herunter, nicht umgekehrt — PDF ist damit die Auflösungs-Untergrenze,
nicht das Web).
Hervorhebungen: wo eine Handlung an einer bestimmten Stelle im Screenshot gezeigt werden soll,
Markierung in Teal (#1fb6a6, konsistent mit der Akzentfarbe aus cd-styleguide.md §7) — kein
Rot/Ad-hoc-Farbe, da Rot in diesem Farbraum für keinen definierten Zweck reserviert ist und mit
Warnfarben verwechselt werden könnte.
Beschriftung: Bildunterschrift „Abb. N: …“ analog zu cd-styleguide.md §10 (8,5 pt, Text
gedämpft, kursiv) — im Web als Alt-Text zusätzlich zur sichtbaren Bildunterschrift (siehe §12
Barrierefreiheit), nicht nur als Alt-Text allein.
Beispieldaten: Screenshots zeigen ausschließlich Testdaten/Demo-Daten, nie reale
Kundendaten/-namen — deckt sich mit den Datenschutz-Prinzipien, die bereits in
help-center/problem-melden.md sichtbar sind (Schwärzung vertraulicher Werte). Testfirmen-/
Testnutzernamen sind erkennbar fiktiv zu wählen (z. B. „Musterfirma GmbH“ statt eines
klingenden Produktivnamens).
Aktualisierungsregeln bei UI-Änderungen: siehe §17 Pflegekonzept.
Naming-Konvention: bereits etabliert für Tutorials
(docs/brand/tutorials-authoring.md §„Naming-Konvention: Screenshots“) —
tutorial-[Nr]-schritt-[Nr]-[beschreibung].png. Dieser Bereich erweitert das Muster auf alle
Dokumentarten: <dokumentart>-<dokument-slug>-<laufende-nr>-<beschreibung>.png, Ablage unter
assets/<dokumentart>/ analog zu assets/tutorials/.
10. Codes, Pfade und Feldnamen
Einheitliche Code-Auszeichnung (Markdown-Backticks) für:
- Feld-/Parameternamen (
Rechnungsnummer,company_id) - Dateipfade (
docs/brand/cd-styleguide.md) - Enum-/Statuswerte (
reviewed,extracted) - Tastenkombinationen (siehe §7)
- Code-Schnipsel/API-Beispiele — mehrzeilig in Codeblöcken (
```) mit Sprachkennzeichnung wo sinnvoll (json,bash), einzeiliger Inline-Code sonst
PDF-Darstellung: techdoc-template.js rendert Inline-Code aktuell nicht typografisch abgesetzt
(kein Monospace-Fallback definiert) — offener Punkt, siehe §16. Bis zur Implementierung:
Inline-Code erscheint im PDF als regulärer Fließtext; das ist eine bekannte, dokumentierte
Abweichung, kein stillschweigend akzeptierter Fehler.
11. Terminologie
Keine Doppelregelung — verbindlich ist ausschließlich CLAUDE.md „Naming (2026-07-12)“
(Organization/Company) und die dort referenzierten @lirai/shared-Enums/FSM-Begriffe, wie bereits
in editorial-guideline.md §3 festgelegt. Ergänzung für technische Dokumente: Terminologie muss an
UI und Dokumentation synchron bleiben — Konsistenzsicherung ist Teil des Pflegekonzepts (§17),
nicht nur ein einmaliger Redaktionsschritt.
12. Versionierung
Übernommen aus Editorial Guideline §6 (Pflichtfelder, Änderungshistorie-Tabelle,
Major/Minor-Zählung) — hier ergänzt um die medienübergreifende Konsequenz: eine Revision, die
Web-Inhalt ändert, muss (bei Single-Source-Dokumenten) automatisch auch die PDF-Ausgabe
aktualisieren; bei den noch manuell gepflegten .cjs-Mirrors (siehe Editorial Guideline §8
Punkt 3) ist der Sync-Schritt Teil derselben Revision, nicht ein separater Folgeauftrag.
Umgang mit veralteten Dokumenten: kein Löschen, Status-Zeile wechselt auf einen expliziten
Vermerk — TR-Entscheidung Rev. 2: umgesetzt. Statuswert Veraltet (Format: Status: Veraltet — siehe [Nachfolgedokument]) ergänzt die drei bestehenden Editorial-Guideline-§6-Werte
Entwurf/Zur Prüfung/Freigegeben, siehe editorial-guideline.md §6 Rev. 4.
13. Ausgabeformate
| Aspekt | Vorgabe |
|---|---|
| Web | Referenzformat, alle Vorgaben in diesem Dokument gelten zuerst hierfür |
| PDF-Download | techdoc-template.js, siehe cd-styleguide.md §5–§10 |
| Ausdruck (Schwarz-Weiß) | Alle drei definierten Akzentfarben (Navy, Teal, Gold) müssen auch in Graustufen unterscheidbar bleiben — Navy/Teal/Gold haben ausreichend unterschiedliche Helligkeitswerte (dunkel/mittel/hell), keine reine Farbcodierung ohne zusätzliches Label oder Symbol als einzige Bedeutungsträgerin (gilt insbesondere für die vier Hinweisbox-Typen aus §8 — jede hat zusätzlich zur Farbe ein Textlabel „Hinweis:“/„Voraussetzung:”/„Tipp:“/„Achtung:”) |
| Mobilgeräte | Web-Ausgabe muss responsiv reflowen (Aufgabe des Dokumentationsservers/lirai-www, keine gesonderte Mobil-Vorlage in diesem Repo) — Tabellen mit vielen Spalten (§6) sind ein bekanntes Risiko für schmale Viewports, siehe §16 offene Punkte |
14. Barrierefreiheit
- Kontraste: alle in
cd-styleguide.md§7 definierten Text-auf-Hintergrund-Kombinationen (Navy auf Weiß, Navy auf Teal-hell, Navy auf Gold-hell, Navy auf Navy-hell) erfüllen WCAG AA für Fließtext (dunkle Schrift auf hellen Flächen, keine der Flächenfarben ist dunkler als „hell“). - Alternativtexte: jedes Bild/Screenshot bekommt einen Alt-Text, der den Zweck der Abbildung
beschreibt (nicht nur „Screenshot“) — siehe bereits umgesetztes Muster in
handbook/tutorials/01-erste-schritte.md(![Screenshot: Upload-Button in der Hauptansicht]). - Dokumentstruktur: durchgehende Überschriftenhierarchie ohne übersprungene Ebenen (kein H3 ohne vorangehendes H2 im selben Abschnitt) — Voraussetzung für Screenreader-Navigation und automatische Inhaltsverzeichnisse (§5).
15. Muster- und Vorlagendokumente
Drei Dokumentarten, mit Positiv- und Negativbeispiel je Typ (LIR-2890 Deliverable 4).
Muster A — Handbuch-Kapitel
Positivbeispiel (Struktur/Layout, TR-Korrektur Rev. 2): die Kopiervorlage
handbook/tutorials/00-template.md sowie
Tutorial: Erste Schritte als
strukturelles Vorbild (Zielfrage im Einstiegssatz, klare Schritt-Struktur,
Code/Fettschrift-Konvention aus §7, Screenshots mit beschreibendem Alt-Text,
Änderungshistorie-Tabelle). Hinweis: 01-erste-schritte.md steht selbst noch auf Status
„Entwurf“ und ist laut Fachprüfung LIR-2896 fachlich nicht freigegeben
(u. a. dort verwendete Status „Extracted“/„Reviewed“ existieren nicht im echten Dokument-FSM,
siehe TR-Korrektur in §7); Korrektur läuft in einem separaten Durchgang. Als Beleg für Layout/
Auszeichnungs-Konvention bleibt die Datei trotzdem geeignet — nur ihr fachlicher Inhalt ist noch
nicht verlässlich, nicht ihre Struktur.
Negativbeispiel (zur Verdeutlichung, nicht im Repo abgelegt):
# Upload
Man klickt auf das Symbol oben und lädt dann die Datei hoch, danach passiertdie Erkennung automatisch und man kann das dann prüfen und freigeben jenachdem was für eine Rolle man hat und dann ist es fertig.Verstöße: keine Zielfrage/kein Einstiegssatz, keine Schrittgliederung (Fließtextblock statt
### Schritt N), keine Auszeichnung von Button/Statuswerten (§7), kein Screenshot, kein
Kopfzeilen-Block, „man“-Passivkonstruktion statt „Sie“ (Editorial Guideline §3).
Muster B — Release Note
Positivbeispiel:
Status: Freigegeben | Autor: Technischer Redakteur (TR) | Fachprüfung: CTO ([LIR-XXX](/LIR/issues/LIR-XXX)) |Quelle-Ticket: [LIR-XXX](/LIR/issues/LIR-XXX) | Stand: 2026-07-26 (Rev. 1) | Softwarestand: v2026.7
# Release Notes — v2026.7 (26. Juli 2026)
## Neuerungen
- **E-Mail-Import:** Rechnungen können jetzt automatisch per E-Mail-Anhang importiert werden, siehe [Tutorial: E-Mails automatisch importieren](/tutorials/email-import/).
## Fehlerbehebungen
- Der Status-Übergang von `todiscuss` zu `approved` schlug in seltenen Fällen bei gleichzeitiger Bearbeitung durch zwei Nutzer:innen fehl. Behoben in [LIR-XXX](/LIR/issues/LIR-XXX).
## Breaking Changes
Keine.Erfüllt: Softwarestand im Kopf (§4), klare Dreiteilung Neuerungen/Fixes/Breaking Changes (Editorial Guideline §4), Ticket-Rückverweise, Querverweis statt Doppelerklärung.
Negativbeispiel:
# Update 2026.7
Ein paar kleine Verbesserungen und Bugfixes. E-Mail Import ist jetzt auch dabei,außerdem noch diverse interne Optimierungen und Performance-Verbesserungen.Verstöße: kein Kopfzeilen-Block, keine Versionsklarheit (Markenkern-Anforderung 1 aus §0), keine Trennung Neuerungen/Fixes/Breaking Changes, „diverse interne Optimierungen“ ist keine nachvollziehbare Aussage (verstößt gegen „Vollständigkeit“ aus dem Markenkern).
Muster C — FAQ-Artikel
Positivbeispiel: help-center/problem-melden.md (bereits
freigegeben und live). Erfüllt: Kurzfrage als Titel, „Antwort vor Kontext“ (Kurzfassung direkt nach
dem Kopf, Details in eigenen Unterabschnitten mit weiteren Fragen als H2), Fettschrift für
UI-Elemente (§7) bereits konsistent verwendet.
Negativbeispiel:
# Problem melden
Falls es mal ein Problem gibt, dann kann man das über verschiedene Wege melden,zum Beispiel gibt es dafür einen Button irgendwo im Portal, und dann wird mandurch einen Dialog geführt der einem hilft die Meldung abzuschicken.Verstöße: Titel ist kein „Wie …?“-Format (§4 Dokumentarten/Editorial Guideline §4), Antwort steht nicht zuerst („Antwort vor Kontext” verletzt), vage Formulierung „irgendwo im Portal“ statt konkretem Ort (verstößt gegen Markenkern „Nachvollziehbarkeit“), kein Button-Wortlaut in Fettschrift.
16. Konsistenzprüfung
| Aspekt | Quelle | Ergebnis |
|---|---|---|
| Farbpalette, Typografie, Logo | cd-styleguide.md §3–§8 |
✅ vollständig übernommen, keine Abweichung; einzige Ergänzung ist die neue Farbe „Navy hell“ (§7 dort, Rev. 6) für den neuen prereq-Blocktyp — gleiche Herleitungslogik wie „Gold hell“ |
| Sprache, Tonalität, Terminologie | editorial-guideline.md §3 |
✅ keine Doppelregelung — dieser Bereich verweist statt zu wiederholen (siehe §0, §11 dieses Dokuments) |
Funktionale Eignung Blocktypen prereq/tip, Kopfzeilenfelder, Statuswert „Veraltet“ |
TR-Fachprüfung Rev. 2 | ✅ bestätigt, in editorial-guideline.md §6 (Rev. 4) übernommen; ein Beispielwert im ursprünglichen Entwurf (§7) korrigiert, siehe dort |
| Webseiten-Layout (lirai-www) | CD-Manual — Webseite | ✅ seit Rev. 3 (LIR-2895) als eigenständiges CD-Dokument vorhanden, siehe §17.3 |
17. Pflegekonzept
17.1 Screenshots aktuell halten
Automatisierte QS (tote Links, veraltete Screenshots) ist laut Editorial Guideline §8 Punkt 2 noch nicht als CI-Schritt umgesetzt. Bis dahin konkreter Interims-Vorschlag (MarketingLead, TR entscheidet Umsetzung):
- Jedes Verzeichnis mit Screenshots (
assets/tutorials/, künftigassets/<dokumentart>/) erhält eine Manifest-Datei (_screenshots.mdoder vergleichbar), die pro Bild den referenzierten UI-Bereich/die Route notiert (z. B.tutorial-01-schritt-01-upload-button.png→ Dokumentübersicht, Upload-Button). - Auslöser für eine Prüfung: (a) jede Editorial-Guideline-§5-Aktualitätsprüfung durchsucht das
Manifest nach UI-Bereichen, die laut
docs/state.mdseit dem Screenshot-Datum verändert wurden; (b) GUIDeveloper/CTO meldet bei UI-Änderungen, die dokumentierte Screens betreffen, proaktiv an TR (analog zum bereits etablierten KM→TR-Pull-Prinzip aus Editorial Guideline §1, hier als Push-Ausnahme für UI-Breaking-Changes). - Langfristig (Folgeempfehlung, nicht Teil dieses Tickets): CI-Schritt, der geänderte
Frontend-Routen (
apps/web/src/**) gegen das Screenshot-Manifest abgleicht und betroffene Dokumente markiert — technische Umsetzung liegt bei CTO/GUIDeveloper, nicht bei MarketingLead oder TR.
17.2 Terminologie konsistent halten
@lirai/shared(Enums, FSM-Zustände, i18n-Strings) bleibt die einzige Quelle für Status-/ Feldnamen — TR fragt bei jeder Zuarbeit den aktuellen Stand ab (bereits etabliertes Prinzip, Editorial Guideline §1), keine gecachte Kopie in der Dokumentation.- Bei Terminologie-Änderungen im Code (Rename von Enums/UI-Beschriftungen) meldet CTO dies an TR analog zum KM-Wissenslücken-Meldeweg (Editorial Guideline §7) — Push-Ausnahme wie in §17.1 Punkt 2, da eine reine Pull-Erkennung Terminologie-Drift erst bei der nächsten turnusmäßigen Prüfung fände.
- MarketingLead prüft ausschließlich CD-Terminologie (Markenname „LirAI Next“/„LirAI“, Claim,
siehe
cd-styleguide.md§2/§4) — Produktterminologie bleibt vollständig TR-Zuständigkeit.
17.3 Offene Anschlussfrage — Webseiten-CD (geschlossen, Rev. 3)
Die Konsistenzprüfung mit dem Webseiten-Layout (lirai-www) aus LIR-2890 §7
war offen, bis das Webseiten-CD eigenständig dokumentiert ist. Mit
CD-Manual — Webseite (LIR-2895) liegt dieses
Referenzdokument nun vor — Farbpalette, Typografie-Herkunft (cd-styleguide.md) und Abgrenzung
zu diesem Dokument sind dort in §0/§13 explizit geprüft und konsistent. Punkt geschlossen.
18. Offene Punkte
- PDF-Inline-Code-Darstellung (§10) —
techdoc-template.jshat keinen Monospace-Fallback. Spec-only bis zum ersten Dokument, das es tatsächlich braucht (analoges Vorgehen zutable/prereq/tip). - PDF-Inhaltsverzeichnis (§5) — noch nicht implementiert, betrifft nur die längeren Referenzdokumente (CD-Manual, Styleguide, künftige Datenblätter).
- Onboarding-/Schulungsunterlagen-Layout (§2) — noch keine erste Publikation, ggf. eigener Foliensatz-Sonderfall nötig; zurückgestellt bis zum ersten konkreten Bedarf.
- Mobil-Darstellung breiter Tabellen (§13) — Risiko benannt, keine Lösung in diesem Ticket; Aufgabe des Dokumentationsservers (lirai-www), sobald Tabellen-lastige Dokumente dort live sind.
- Statuswert „Veraltet“ (§12) — ✅ umgesetzt Rev. 2, siehe
editorial-guideline.md§6 (Rev. 4).
19. Freigabestatus
- MarketingLead (gestalterische Aspekte — §0, §4 Layout, §5 Typografie, §6, §8 Farb-/ Typografie-Spezifikation, §9, §13, §14, §15 visuelle Muster): freigegeben mit Rev. 1.
- Technical Writer (funktionale Aspekte — §2 Dokumentarten-Erweiterung, §4 Pflichtfeld-Erweiterung, §7 Handlungsanweisungs-Konvention, §8 Verwendungsregeln, §12 Statuswert-Erweiterung, §15 inhaltliche Korrektheit der Muster): freigegeben mit Rev. 2, mit drei Korrekturen gegenüber dem Entwurf (siehe §7 FSM-Beispielwert und Schrittüberschrift-Format, §15 Muster-A-Zitat, §15 Muster-B-Statuscode) — Details je in den betroffenen Abschnitten vermerkt.
Akzeptanzkriterium 6 aus LIR-2899 („Freigabe durch Marketing Lead und Technical Writer erfolgt“) ist damit vollständig erfüllt.
Änderungshistorie
| Datum | Rev. | Änderung | Bezugs-Ticket |
|---|---|---|---|
| 2026-07-26 | 1 | Ersterstellung: vollständiger gestalterischer Entwurf für den Bereich technische Dokumente (Dokumentkopf, Gliederung, Textgestaltung, Handlungsanweisungen, Hinweisboxen, Screenshots, Codes, Terminologie, Versionierung, Ausgabeformate, Barrierefreiheit, drei Muster-/Vorlagendokumente, Pflegekonzept, Konsistenzprüfung); Blocktypen prereq/tip in cd-styleguide.md (Rev. 6) ergänzt. Funktionale TR-Bestätigung ausständig |
LIR-2899 |
| 2026-07-26 | 2 | Funktionale TR-Fachprüfung: §2/§4/§8/§12 bestätigt (Kopfzeilenfelder „Softwarestand“/„Gültigkeit“ und Statuswert „Veraltet“ in editorial-guideline.md §6 Rev. 4 umgesetzt); §7 Konvention bestätigt mit zwei Korrekturen (FSM-Beispielwert reviewed→approved, existiert nicht im echten Invoice-FSM; Schrittüberschrift-Format ### Schritt N: als verbindlich bestätigt, 00-template.md angeglichen); §15 Muster A um Klarstellung ergänzt, dass 01-erste-schritte.md fachlich noch nicht freigegeben ist (LIR-2896); §15 Muster B Statuscode-Beispiel korrigiert (reviewed→todiscuss). Status auf Freigegeben gesetzt, AK6 vollständig erfüllt |
LIR-2899 |
| 2026-07-26 | 3 | §16/§17.3 aktualisiert: offener Anschlusspunkt „Webseiten-CD“ geschlossen, jetzt referenziert auf neues CD-Manual — Webseite | LIR-2895 |