Dokumentations-Stilhandbuch

Dieses Handbuch definiert, wie die EmDash-Dokumentation geschrieben wird. Beiträge werden entsprechend angepasst. Sie müssen es nicht auswendig lernen — Reviewer und Editoren helfen — aber das Befolgen beschleunigt die Zusammenführung eines Beitrags.

Dokumentation existiert, um jemandem zu helfen, etwas zu tun und dann zu seinem Projekt zurückzukehren. Schreiben Sie für einen Leser, der müde ist, in Eile, in einer Zweitsprache liest oder neu im Stack ist. Dienen Sie diesem Leser über alles andere.

Lesbarkeit

Bevorzugen Sie:

• Kurze Sätze und kurze Absätze.
• Einfaches Vokabular statt Fachjargon.
• Abkürzungen und Akronyme beim ersten Mal ausgeschrieben.
• Überschriften und Listen zum Aufbrechen langer Passagen.
• Aktive Stimme.

Dokumentieren Sie, wie man mit EmDash baut, nicht wie EmDash gebaut ist. Implementierungsdetails gehören nur dann in die Dokumentation, wenn sie eine Entscheidung ändern, die der Leser treffen muss (wann einen nicht-standardmäßigen Wert wählen, ein Vorbehalt, der sein Projekt betrifft). Sie ersetzen niemals ein Verwendungsbeispiel.

Für Nicht-EmDash-Themen — TypeScript, das AT Protocol, Webfonts, SQL — verlinken Sie auf eine seriöse Quelle, anstatt sie zu erklären. Dokumentieren Sie, was jemand wissen muss, um die Funktion in EmDash zu verwenden.

Was betont werden soll

Die Betonung einer Seite muss durch das bestimmt werden, was der Leser für seine Aufgabe braucht, niemals durch das, was für die EmDash-Entwickler interessant oder aktuell war. Drei Gewohnheiten, denen aktiv widerstanden werden sollte:

• Gewichtung nach Aktualität der Erstellung. Eine Entscheidung, die neu ist oder dem Autor frisch im Gedächtnis, ist kein Grund, sie hervorzuheben. Das am meisten geänderte Ding ist selten das wichtigste für einen Leser. Ordnen Sie Abschnitte, Listenelemente und Überschriften danach, wie oft ein Leser sie braucht, nicht danach, wann sie hinzugefügt wurden. Wenn Sie etwas dokumentieren, weil es sich gerade geändert hat, schreiben Sie wahrscheinlich einen Changelog-Eintrag, keine Dokumentation.

• Entwickler-Relevanz über Leser-Relevanz. Interne Architektur und Designentscheidungen, die bedeutend zu treffen waren, sind in der Regel unsichtbar und irrelevant für die Nutzung. Nennen Sie die Fähigkeit, die der Leser erhält, nicht den Mechanismus dahinter. Ein Leser, der eine Sammlung definiert, muss nicht wissen, wo das Schema gespeichert ist, genausowenig wie er die Sprache des Parsers kennen muss. Wenn der Mechanismus tatsächlich jemandem hilft, der an EmDash arbeitet, gehört er in die Interna-Dokumentation, nicht auf eine benutzerseitige Seite.

• Strohmann-Selbstdefinition. Definieren Sie EmDash nicht durch Kontrast mit einer Karikatur anderer Tools (“Im Gegensatz zu den meisten CMSs…”, “Traditionelle CMSs zwingen Sie…”, “in vielen CMSs deklariert man X im Code”). Beschreiben Sie, was EmDash tut, direkt, und lassen Sie es für sich stehen. Vergleich ist nur erlaubt, wenn der Vergleich die eigene Frage des Lesers ist: auf der Evaluierungsseite und den “Coming from…”-Orientierungsseiten. Auch dort muss er spezifisch und fair sein — konkrete Verhaltensweisen und Kompromisse, kein Strohmann, den der Leser ablehnen soll.

• Definition durch Negation. Eine Fähigkeit als die Arbeit zu rahmen, die man nicht tun muss — “keine Migration zu schreiben”, “kein Rebuild”, “ohne Code zu berühren”, “kein separater Dienst” — ist ein getarnter Strohmann: Er funktioniert nur für einen Leser, der die Alternative trägt, die Sie für ihn erfunden haben. Nennen Sie, was der Leser tut und was passiert. “Fügen Sie ein Feld im Admin-Panel hinzu; es wird sofort wirksam” — nicht “fügen Sie ein Feld ohne Migration, ohne Rebuild, ohne Code hinzu”. Die Ausnahme ist ein konkretes, leserrelevantes Verhalten, das positiv formuliert wird: “Inhalte werden zur Laufzeit bereitgestellt, daher erscheinen Änderungen sofort” ist eine Tatsache über EmDash; “keine Rebuilds nötig” ist dieselbe Tatsache, formuliert als jemand anderes abwesender Schmerz — bevorzugen Sie ersteres.

Der Test für jeden Satz: Wäre ein Leser, der versucht, seine Aufgabe zu erledigen, schlechter dran, wenn er gelöscht würde? Wenn nicht, löschen Sie ihn. Wenn er nur für einen Leser Sinn ergibt, der EmDash mit etwas anderem vergleicht, ist er am falschen Ort oder sollte gestrichen werden.

Zeitlos, nicht Changelog

Benutzerseitige Seiten beschreiben, wie EmDash jetzt funktioniert, für einen Leser, der keine frühere Version im Kopf hat. Kein “jetzt”, “nicht mehr”, “früher”, “anstelle des alten”, “dies hat sich geändert”. Versions-zu-Versions-Unterschiede existieren nur in einem Upgrade-Handbuch. Dass ein Konzept kürzlich eingeführt wurde, ist niemals ein Grund zu erwähnen, dass es kürzlich ist.

Stimme und Ton

Schreiben Sie neutrale, sachliche Sätze. Nennen Sie Fakten direkt.

✅ Plugins laufen in einer isolierten Laufzeitumgebung und können nur auf die APIs zugreifen, die sie deklarieren.

❌ Plugins leben in einer gemütlichen kleinen Sandbox, in der nichts Schlimmes jemals passieren kann!

• Verwenden Sie nicht wir, uns, unser oder lasst uns. Sie sitzen nicht beim Leser. Formulieren Sie um, um den Leser direkt anzusprechen oder das System zu beschreiben.
• Verwenden Sie niemals ich. Dokumentation handelt nicht vom Autor.
• Sprechen Sie den Leser als Sie an, wenn nötig, besonders um einen Schritt zu kennzeichnen, bei dem etwas schiefgehen kann.
• Erzählen Sie keine Geschichte. Kein “Nachdem wir nun X eingerichtet haben, gehen wir zu Y über”. Beginnen Sie einen Abschnitt mit dem Ziel, dann den Schritten.
• Vermeiden Sie Wortspiele, Maskottchen und kulturelle Referenzen. Sie erhöhen den Leseaufwand und lassen sich nicht übersetzen.
• Ausrufezeichen sind selten. Verwenden Sie eines nur für etwas wirklich Ermutigendes oder Überraschendes. Im Zweifel verwenden Sie einen Punkt.

Überschriften

• Der Seitentitel ist das <h1> (aus dem Frontmatter title). Abschnitte beginnen bei <h2>.
• Halten Sie Überschriften kurz. <h2> und <h3> erscheinen in der “Auf dieser Seite”-Seitenleiste; schauen Sie sich die Vorschau an und kürzen Sie alles, was umbricht.
• Keine abschließende Interpunktion, einschließlich Doppelpunkt.
• Formatieren Sie Code in Überschriften als <code> wie im Fließtext.

Listen

• Verwenden Sie eine Aufzählung, wenn die Reihenfolge keine Rolle spielt, wie bei einer Reihe von Optionen oder Eigenschaften.
• Verwenden Sie eine nummerierte Liste für Schritte, die in der Reihenfolge befolgt werden müssen. Verwenden Sie die Starlight-Komponente <Steps> für Verfahren.
• Wenn Listenelemente zu mehreren Absätzen anwachsen oder mehrere Codebegriffe enthalten, wechseln Sie stattdessen zu <h3>-Abschnitten.

Beispiele

• “zum Beispiel” in voller Länge führt ein einzelnes Beispiel oder Hypothetisches ein.
• “z.B.” in Klammern führt eine nicht erschöpfende Liste ein (z.B. GitHub, GitLab).
• Eine Liste, die jede Option abdeckt, ist keine Beispielliste — verwenden Sie Klammern ohne “z.B.” (die erforderlichen Eigenschaften (src, alt)).

Screenshots

Verwenden Sie einen Screenshot nur, wenn er räumliche Zusammenhänge, einen Interfacezustand oder die Position von Steuerelementen wesentlich verdeutlicht. Halten Sie Anweisungen und andere wesentliche Informationen im Text, damit die Seite auch ohne Bild nutzbar bleibt.

Jeder Screenshot muss aktuell sein und für den spezifischen Zweck der Seite aufgenommen werden. Geben Sie Alt-Text an, der den relevanten Bildschirm und Zustand beschreibt. Notieren Sie Fixture, Route, Viewport, Locale und Theme, damit ein anderer Contributor die Aufnahme reproduzieren kann.

Codebeispiele

Codebeispiele sind genauso wichtig wie der Text um sie herum.

Führen Sie jeden Codeblock mit einem vollständigen, eigenständigen Satz in einer eigenen Zeile ein, der dem Leser sagt, was der Block tut. Beginnen Sie nicht mit einem Satzfragment, das mit einem Doppelpunkt endet, einer nackten Überschrift oder “wie folgt:”.

✅ Das folgende Beispiel registriert ein Plugin im sandboxed-Array:

❌ Fügen Sie das Plugin wie folgt hinzu:

Die Einführung bereitet den Leser darauf vor, was der Code tut, sodass er nur noch herausfinden muss, wie. Sie erstellt auch ein Lückenmuster für einen Leser, der etwas leicht Abweichendes tut.

Innerhalb eines <Steps>-Verfahrens ist eine direkte imperative Anweisung die Einführung (“Fügen Sie eine tsconfig.json hinzu:” gefolgt von der Datei ist in einem nummerierten Schritt in Ordnung).

Weitere Regeln:

• Verwenden Sie echten, funktionierenden Code. Kein foo/bar. Zeigen Sie eine realistische Konfiguration, nicht jeden möglichen Wert — der Leser wird nur eine haben.

• Fügen Sie einen title=-Dateinamen zu jedem Block hinzu, der eine Datei darstellt, damit der Leser weiß, wohin der Code gehört.

  ```ts title="src/plugin.ts"

• Verwenden Sie Expressive-Code-Annotationen, keine rohen ```diff-Fences, für Vorher/Nachher-Änderungen. Markieren Sie geänderte Zeilen mit del={n} / ins={n} oder geänderten Text mit del="…" / ins="…". Halten Sie Diffs minimal und lokal auf die sich ändernden Zeilen.

  Das folgende Beispiel zeigt eine einzelne Zeilenänderung:

  ```ts del={1} ins={2}
  import { definePlugin } from "emdash";
  import type { SandboxedPlugin } from "emdash/plugin";
  ```

• Prüfen Sie gerenderten Code lokal vor dem Einreichen. Ein Tippfehler kann die Anzeige beschädigen.

Upgrade- und Migrationsanleitungen

Eine Anleitung, die einem Leser hilft, ein bestehendes Projekt auf eine neue Version zu bringen, folgt einer festen Struktur. Die “Was soll ich tun?”-Abschnitte sind der Teil, den Leser am meisten schätzen — sparen Sie nicht daran.

Beginnen Sie mit: wie man aktualisiert, einem Hinweis, dass Dinge möglicherweise “einfach funktionieren”, aber weiterlesen sollte, wenn nicht, und einem Link zum Changelog.

Listen Sie dann jede brechende Änderung als eigenen Eintrag auf:

### [Umbenannt/Geändert/Entfernt/Veraltet]: <Feature>

In früheren Versionen, <ein Satz, Vergangenheitsform, was es tat>.

<Ein Satz, Gegenwartsform, wie es jetzt funktioniert>.

#### Was soll ich tun?

<Imperativ-Aktionen: Aktualisieren… / Ersetzen… / Entfernen…, mit einem minimalen Diff.>

Wählen Sie das Verb danach, wie der Leser die Auswirkung empfindet. Wenn ein neuer Standard seinen Wert ersetzt, ist das ein “Geändert: Standardwert”, nicht ein “Hinzugefügt: Option”.

Eine brechende Änderung ist eine, die eine Änderung am Projekt des Lesers erfordert, oder es funktioniert nicht mehr. Geben Sie die Aktion an, nicht nur die Tatsache. Nicht “die minimale Node.js-Version ist jetzt X”, sondern “überprüfen Sie Ihre Node.js-Version mit dem folgenden Befehl und aktualisieren Sie, wenn sie unter X liegt”.

EmDash-Spezifika

Konventionen für wiederkehrende Situationen, sortiert nach der Häufigkeit, mit der ein Contributor darauf trifft. Dies ist eine Liste von Konventionen, kein Ranking, welche Features wichtiger sind.

Plugins: Sandboxed vs. nativ

Sandboxed und native Plugins sind verschiedene Formate mit verschiedenen Erstellungsmustern. Eine Änderung an einem betrifft selten das andere. Geben Sie an, welches Format eine Seite oder ein Beispiel behandelt. Wenn Sie eine Sandboxed-Plugin-Seite bearbeiten, ändern Sie keine nativen Plugin-Beispiele und umgekehrt.

Lokalisierung

Fügen Sie keine messages.po-Änderungen in einen Docs-PR ein. Ein Workflow extrahiert Kataloge beim Merge nach main. Das Einbeziehen verursacht Churn und Merge-Konflikte.

Experimentelle Features

Ein Feature hinter einem experimentellen Flag oder ein instabiles Wire-Format unter einem RFC kann sich ohne Vorankündigung ändern. Halten Sie die Dokumentation schlank, kennzeichnen Sie es mit einem Warnungs-<Aside> und verweisen Sie auf den RFC oder die Diskussion als Wahrheitsquelle. Dokumentieren Sie eine instabile Oberfläche nicht in erschöpfendem Detail.

Atmosphere-Konten

Wenn die portable, nutzereigene Identität hinter Bluesky und dem breiteren AT-Protocol-Netzwerk auftaucht, nennen Sie es ein Atmosphere-Konto und verwenden Sie diesen Begriff konsequent. Verlinken Sie die erste Erwähnung auf die Atmosphere-Login-Anleitung oder atmosphereaccount.com. did:plc:… und Handles sind seine konkreten Bezeichner; verwenden Sie sie, wenn ein Literalwert benötigt wird.

Dokumentation ist Code

Die Dokumentationssite ist ein EmDash-nahestehendes Astro-Projekt. Dokumentationsänderungen durchlaufen denselben Pull-Request- und Review-Flow wie Code. Jede Textänderung wartet auf ein Review; eine Formulierungsänderung kann die Bedeutung eines Satzes verschieben oder passende Änderungen an anderer Stelle auf der Site erfordern. Kleine, geprüfte, konsistente Änderungen halten die gesamte Site kohärent.