Dokumentations-Stilrichtlinie

Diese Richtlinie definiert, wie die EmDash-Dokumentation geschrieben wird. Beiträge werden entsprechend angepasst. Sie müssen sie nicht auswendig lernen – Reviewer und Redakteure helfen dabei – aber wenn Sie ihr folgen, wird ein Beitrag schneller zusammengeführt.

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, es eilig hat, in einer Zweitsprache liest oder neu im Stack ist. Dienen Sie diesem Leser vor allem anderen.

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, um lange Passagen aufzubrechen.
• 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 ein nicht-standardmäßiger Wert gewählt werden soll, ein Vorbehalt, der sein Projekt betrifft). Sie ersetzen niemals ein Verwendungsbeispiel.

Für Nicht-EmDash-Themen – TypeScript, das AT Protocol, Web-Fonts, 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 zu betonen ist

Der Schwerpunkt einer Seite muss durch das bestimmt werden, was der Leser braucht, um seine Aufgabe zu erledigen, niemals durch das, was für die Leute interessant oder aktuell war, die EmDash gebaut haben. Drei Gewohnheiten, denen aktiv zu widerstehen ist:

• Autorengewichtung nach Aktualität. Dass eine Entscheidung neu ist oder frisch im Kopf des Autors, 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.

• Erbauer-Relevanz über Leser-Relevanz. Interne Architektur- und Designentscheidungen, die bedeutsam zu treffen waren, sind normalerweise unsichtbar und irrelevant für die Verwendung. Geben Sie die Fähigkeit an, die der Leser erhält, nicht den Mechanismus dahinter. Ein Leser, der eine Collection definiert, muss nicht wissen, wo das Schema gespeichert ist, genauso wenig wie er die Sprache des Parsers kennen muss. Wenn der Mechanismus wirklich jemandem hilft, der an EmDash arbeitet, gehört er in die Internals-Dokumentation, nicht in eine benutzerseitige Seite.

• Strohmann-Selbstdefinition. Definieren Sie EmDash nicht durch Kontrast mit einer Karikatur anderer Tools („Im Gegensatz zu den meisten CMS…”, „Traditionelle CMS zwingen Sie dazu…”, „in vielen CMS deklarieren Sie X im Code”). Beschreiben Sie, was EmDash tut, direkt, und lassen Sie es für sich selbst sprechen. Vergleich ist nur erlaubt, wenn der Vergleich die eigene Frage des Lesers ist: auf der Evaluierungsseite und den „Kommen von…”-Orientierungsseiten. Auch dort muss er spezifisch und fair sein – konkrete Verhaltensweisen und Abwägungen, kein Strohmann, den der Leser ablehnen soll.

• Definition durch Negation. Eine Fähigkeit als Arbeit zu formulieren, die man nicht tun muss – „keine Migration zu schreiben”, „kein Rebuild”, „ohne Code zu berühren”, „kein separater Service” – ist ein getarnter Strohmann: Er funktioniert nur für einen Leser, der die Alternative mitbringt, die Sie für ihn erfunden haben. Geben Sie an, 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, für den Leser relevantes Verhalten, das positiv formuliert ist: „Inhalte werden zur Laufzeit bereitgestellt, sodass Änderungen sofort erscheinen” ist eine Tatsache über EmDash; „keine Rebuilds erforderlich” ist dieselbe Tatsache, formuliert als fremder abwesender Schmerz – bevorzugen Sie das erste.

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

Immer aktuell, kein 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”, „das hat sich geändert”. Versions-zu-Versions-Unterschiede leben nur in einer Upgrade-Anleitung. Dass ein Konzept kürzlich eingeführt wurde, ist niemals ein Grund zu erwähnen, dass es neu ist.

Stimme und Ton

Schreiben Sie neutrale, sachliche Sätze. Geben Sie Fakten direkt an.

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

❌ Plugins leben in einer gemütlichen kleinen Sandbox, wo niemals etwas Schlimmes passieren kann!

• Verwenden Sie nicht wir, uns, unser oder lass uns. Sie sitzen nicht beim Leser.
• 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 nicht und erzählen Sie keine Geschichte. Kein „jetzt, da wir X eingerichtet haben, fahren wir mit Y fort”. Beginnen Sie einen Abschnitt mit dem Ziel, dann den Schritten.
• Vermeiden Sie Schrulligkeit, 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. Wenn Sie unsicher sind, 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; sehen Sie sich die Vorschau an und kürzen Sie alles, was umbricht.
• Keine abschließende Interpunktion, einschließlich eines Doppelpunkts.
• Formatieren Sie Code als <code> in Überschriften genauso wie im Fließtext.

Listen

• Verwenden Sie eine Aufzählungsliste, wenn die Reihenfolge keine Rolle spielt, z. B. eine 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-<Steps>-Komponente für Verfahren.
• Wenn Listenelemente in mehrere Absätze hineinwachsen oder mehrere Code-Begriffe tragen, wechseln Sie stattdessen zu <h3>-Abschnitten.

Beispiele

• „zum Beispiel” vollständig führt ein einzelnes Beispiel oder eine Hypothese 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)).

Code-Beispiele

Code-Beispiele sind genauso wichtig wie die Prosa um sie herum.

Führen Sie jeden Code-Block mit einem vollständigen, eigenständigen Satz in einer eigenen Zeile ein, der dem Leser sagt, was der Block tut. Leiten Sie nicht mit einem Satzfragment ein, das mit einem Doppelpunkt endet, einer bloßen Überschrift oder „so:”.

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

❌ Fügen Sie das Plugin so hinzu:

Die Einleitung bereitet den Leser darauf vor, was der Code tut, sodass er nur herausfinden muss wie. Sie schafft auch ein Lückenfüller-Muster für einen Leser, der etwas leicht Anderes tut.

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

Andere 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 hinzu zu jedem Block, 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 -Zäune, 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 zu den Zeilen, die sich ändern.

  Das folgende Beispiel zeigt eine einzelne Zeile, die sich ändert:

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

• Sehen Sie sich gerenderten Code lokal in der Vorschau an, bevor Sie einreichen. Ein Tippfehler kann die Anzeige unterbrechen.

Upgrade- und Migrations-Anleitungen

Eine Anleitung, die einem Leser hilft, ein bestehendes Projekt auf eine neue Version zu verschieben, 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 upgradet, einem Hinweis, dass Dinge „einfach funktionieren” können, aber weiterlesen, wenn nicht, und einem Link zum Changelog.

Listen Sie dann jede Breaking Change als eigenen Eintrag auf:

### [Renamed/Changed/Removed/Deprecated]: <feature>

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

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

#### Was soll ich tun?

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

Wählen Sie das Verb danach, wie der Leser die Auswirkung spürt. Wenn ein neuer Standardwert ihren Wert ersetzt, ist das eine „Changed: default value”, keine „Added: option”.

Eine Breaking Change ist eine, die eine Änderung am Projekt des Lesers erfordert, sonst funktioniert es nicht mehr. Geben Sie die Aktion, 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 upgraden Sie, wenn sie unter X ist”.

EmDash-Spezifika

Konventionen für wiederkehrende Situationen, geordnet danach, wie oft ein Mitwirkender auf sie trifft. Dies ist eine Liste von Konventionen, keine Rangfolge, welche Funktionen wichtig sind.

Plugins: sandboxed vs native

Sandboxed und native Plugins sind verschiedene Formate mit unterschiedlichen Authoring-Formen. Eine Änderung an einem betrifft selten den anderen. Geben Sie an, um welches Format es sich auf einer Seite oder in einem Beispiel handelt. Ändern Sie beim Bearbeiten einer Sandboxed-Plugin-Seite keine Native-Plugin-Beispiele und umgekehrt.

Lokalisierung

Fügen Sie keine messages.po-Änderungen in einem Docs-PR hinzu. Ein Workflow extrahiert Kataloge beim Merge zu main. Sie einzuschließen erzeugt Churn und Merge-Konflikte.

Experimentelle Funktionen

Eine Funktion hinter einem experimentellen Flag oder ein instabiles Wire-Format unter einem RFC kann sich ohne Vorankündigung ändern. Halten Sie ihre Dokumentation schlank, kennzeichnen Sie sie mit einem Vorsichts-<Aside> und verweisen Sie auf das RFC oder die Diskussion als Quelle der Wahrheit. Dokumentieren Sie eine instabile Oberfläche nicht bis ins kleinste Detail.

Atmosphere-Konten

Wenn die portable, benutzereigene Identität hinter Bluesky und dem breiteren AT Protocol-Netzwerk auftaucht, nennen Sie sie ein Atmosphere-Konto und verwenden Sie diesen Begriff konsistent. Verlinken Sie die erste Erwähnung zum Atmosphere-Login-Leitfaden oder atmosphereaccount.com. did:plc:… und Handles sind seine konkreten Identifikatoren; verwenden Sie sie, wo ein Literalwert benötigt wird.

Dokumentation ist Code

Die Dokumentations-Website ist ein EmDash-nahes Astro-Projekt. Dokumentationsänderungen durchlaufen denselben Pull-Request- und Review-Ablauf wie Code. Jede Textänderung wartet auf eine Review; eine Formulierungsänderung kann die Bedeutung eines Satzes verschieben oder passende Änderungen anderswo auf der Website erfordern. Kleine, reviewte, konsistente Änderungen halten die gesamte Website kohärent.