xz1220/feishu-doc-style

Was macht feishu-doc-style?

Schreibregeln für Feishu-Dokumente – gültig für technische Konzepte, PRDs, Retrospektiven und Anleitungen. Einziges Ziel: Jeder versteht es beim ersten Lesen.

Wann verwenden

Immer wenn Sie ein Feishu-Dokument oder ein technisches Dokument schreiben, bearbeiten, überprüfen oder verfeinern, wird dieser Leitfaden standardmäßig angewendet – ohne dass der Benutzer es explizit erwähnen muss.

Wenn der Benutzer explizit /feishu-doc-style eingibt oder fragt „Ist das klar genug geschrieben?“ oder „Wie mache ich diesen Abschnitt verständlich?“, dann beziehen Sie sich auf die „Kernprinzipien“ und die „Pre-Submission-Checkliste“ und schlagen Sie Änderungen vor.

Wenn Sie für jemanden ein Dokument überarbeiten, gehen Sie zuerst die Checkliste Punkt für Punkt durch, identifizieren Sie Verstöße, geben Sie die korrigierte Version und erläutern Sie die Änderungen.

Kernprinzipien

1. Nur das Fazit, keine Herleitung. Streichen Sie Herleitungen wie „Warum diese Wahl getroffen wurde“ oder „Wie die Abwägung war“ – geben Sie direkt das Ergebnis. Der Leser will die Antwort, nicht Ihren Denkprozess.

2. Absätze mit zwei bis drei Zeilen sind genug. Ein Absatz sollte nicht länger als zwei bis drei Zeilen sein. Stapeln Sie nicht mehrere Sätze in einen großen Block. Lange Absätze ermüden den Leser.

3. Prozesse als Diagramm, nicht als Text. Wer zuerst kommt, wie Daten fließen, wie sich der Status ändert – das gehört in ein Diagramm, nicht in einen langen Text. Ein Sequenzdiagramm ersetzt einen ganzen Absatz.

4. Pfeile nur im Diagramm. Im Text und in Tabellen sind Pfeilketten wie „A → B; C → D“ verboten. Sie zwingen den Leser, im Kopf zurückzuverfolgen – das ist das Äquivalent zum Übersetzen für den Leser.

5. In normaler Sprache, kein Fachjargon. Interne Fachbegriffe versteht der Leser nicht. Entweder durch Alltagssprache ersetzen oder beim ersten Auftreten in einem Satz erklären. Eine gängige Fachjargon-Tabelle finden Sie in references/jargon.md.

6. Tabellenzellen als vollständige Sätze. Stapeln Sie keine Abkürzungen in Zellen – schreiben Sie „Wer hat was getan, was war das Ergebnis“.

7. Keine dekorativen Emojis und Hervorhebungsboxen. Emojis wie 📌 ⭐ 🔒 💡 ✅ 🚧 sowie farbige Callout-Hervorhebungsboxen machen die Seite unruhig und unordentlich. Für Betonungen verwenden Sie einen normalen Absatz mit „Fetter Zwischentitel. Gefolgt von Fließtext“; dokumentweite Notizen und Statusanzeigen erfolgen mit `> Zitatblöcken. Im gesamten Dokument sollte kein dekoratives Emoji und keine Hervorhebungsbox vorkommen.

8. Fettschrift sparsam einsetzen. Pro Abschnitt höchstens ein- bis zweimal, nur für echte globale Schlussfolgerungen oder Prinzipien. Begriffen, Feldnamen, Positionsangaben (links / mitte / rechts) werden nicht fett formatiert – die Hierarchie ergibt sich aus Satz- und Tabellenstruktur, nicht aus übermäßiger Fettschrift.

9. Keine Zeichen verwenden, die nicht über die Tastatur eingegeben werden können. Kreisziffern ①②③④⑤, Status-Emojis ✓ ◐ ◑ ● ○, als Symbole verwendete !, Funktionssymbole ⚡ ⌘ – das sind keine Zeichen, die ein Mensch normalerweise tippen würde; sie wirken, als ob die Benutzeroberfläche wörtlich übernommen wurde. Für Aufzählungen verwenden Sie normale nummerierte Listen „1. 2. 3.“ oder „Erstens, Zweitens“; für Status schreiben Sie direkt „Abgeschlossen / In Bearbeitung“; für Schrittnummern verwenden Sie normale Zahlen (Schritt 1 / STEP 1).

10. Überschriften geben den Inhalt an, nicht die Struktur. Eine Überschrift sagt direkt, worum es in diesem Abschnitt geht („Ziele und Hauptmaßnahmen für dieses Jahr“ oder „Aktuelle Arbeiten und Fortschritt“). Verzichten Sie auf organisatorische Logik oder Schreibgerüste. Keine Strukturpräfixe wie „Gesamt:“, „Teil:“, „Abschnitt 1:“ – Hierarchien wie Überblick/Unterteilung, Parallelität/Aufeinanderfolge ergeben sich natürlich aus der Reihenfolge des Inhalts und der Überschriftenebene. Fügen Sie auch keine Metakommentare in die Überschrift ein (Erklärungen wie „(KI fügt täglich hinzu)“ gehören in den Fließtext oder `> Zitatblöcke). Vermeiden Sie es außerdem, den Inhalt in ein unpassendes Rahmenkonzept zu pressen – z. B. „Einige Aufgaben nach Richtung“ in die Zeithülle „Fortschritt erstes Halbjahr“ zu zwängen; überlegen Sie zuerst, was die eigentliche Ordnungsdimension des Inhalts ist (aktueller Status nach Richtung, Fortschritt nach Zeit). Selbsttest: Sprechen Sie die Überschrift laut aus – klingt sie wie ein normaler Titel, den jemand vergeben würde? „Gesamt: Ziele für dieses Jahr“ ist es nicht; „Ziele für dieses Jahr“ schon.

Tabellen richtig schreiben

Spaltennamen in Alltagssprache, am besten als Frage formuliert. Zum Beispiel „Was macht der Benutzer / Was tut das System im Hintergrund / Muss online gewartet werden?“, nicht Begriffe wie „Sync-Eintritt / Async-Pipeline und Persistenz“.

Zellen als vollständige Sätze: Ein Satz, der klar sagt, wer was getan hat und was das Ergebnis ist.

Technische Details gehören in den Fließtext. Die Tabelle dient nur dem Verständnis. Vollständige CREATE-TABLE-Anweisungen, Schnittstellendefinitionen usw. kommen in eigene Abschnitte im Fließtext, nicht in die Tabelle.

Grafiken: Welche Grafik wofür

Prozesse, die grafisch darstellbar sind, nicht in Textform bringen. Wählen Sie die Grafik nach dem aus, was Sie darstellen möchten:

| Was darstellen | Welche Grafik | |---|---| | Logischer Ablauf, Reihenfolge, wie Daten Schritt für Schritt fließen | Sequenzdiagramm (Mermaid sequenceDiagram) mit Swimlanes nach Rollen | | Wie Module geschichtet sind, wer von wem abhängt | Architekturdiagramm (Kartenknoten: Symbol + Titel + ein Satz Erklärung, Farbcodierung nach Schicht) | | Wie sich der Status ändert (z. B. Entwurf → Veröffentlichung → Rücknahme) | Flussdiagramm oder Zustandsdiagramm (Mermaid flowchart) |

Wie Sie diese Grafiken tatsächlich in Feishu einfügen (Mermaid-Zeichenfläche, lark-whiteboard, lark-cli) finden Sie in references/feishu-tooling.md.

Pre-Submission-Checkliste

Vor der Abgabe gehen Sie diese Liste Punkt für Punkt durch – wenn ein Punkt nicht erfüllt ist, zurückgehen und korrigieren:

• Enthalten Fließtext und Tabellen keine Pfeilketten (A → B)? Erscheinen Pfeile nur in Diagrammen?
• Sind alle Absätze auf zwei bis drei Zeilen begrenzt?
• Gibt es unerklärten Fachjargon? Wurde der Begriff beim ersten Auftreten in einem Satz verständlich erklärt?
• Werden Prozesse als Diagramm dargestellt, nicht als Textblock?
• Enthalten Tabellenzellen vollständige Sätze? Sind Spaltennamen in Alltagssprache?
• Wurden lange Herleitungen („Warum haben wir uns so entschieden“) gestrichen, nur das Fazit geblieben?
• Keine dekorativen Emojis, keine farbigen Hervorhebungsboxen (Callouts)? Betonung durch fette Zwischentitel, Notizen durch Zitatblöcke?
• Keine Kreisziffern ①②③, Status-Emojis ✓ ◐ und andere Zeichen, die nicht über die Tastatur eingegeben werden können?
• Fettschrift sparsam – pro Abschnitt höchstens ein- bis zweimal für globale Schlussfolgerungen, keine Fettung von Begriffen oder Positionsangaben?
• Enthalten Überschriften und Tabellen keine nackten englischen Begriffe als Subjekt? Wenn Design-Mockups auf Englisch gegeben sind, gibt es eine chinesische Erläuterung in Klammern?
• Benennen Überschriften den Inhalt direkt, ohne Strukturpräfixe wie „Gesamt:/Teil:/Abschnitt 1:“ oder Metakommentare? Wurde der Inhalt nicht in eine unpassende Zeithülle gezwängt?

Begleitende Referenzen

• references/jargon.md: Tabelle mit Fachjargon-Gegenüberstellung; die Begriffe links werden konsequent durch die Alltagssprache rechts ersetzt; wird fortlaufend ergänzt.
• references/feishu-tooling.md: Gedächtnisstütze, wie Sie Grafiken in Feishu einfügen (Mermaid-Zeichenfläche, lark-whiteboard, lark-cli).

Dieses Skill hält sich selbst an diese Regeln

Die SKILL.md, README und references dieses Skills folgen den obigen Prinzipien. Wenn Sie es ändern, nehmen Sie zuerst die „Pre-Submission-Checkliste“ als Selbstkontrolle: keine dekorativen Emojis, keine Pfeilketten, kurze Absätze, Überschriften mit Inhalt. Wenn sich Regeln ändern, aktualisieren Sie gleichzeitig SKILL.md und README – lassen Sie nicht zu, dass sie inkonsistent werden.