Schreibstil-Leitfaden

Allgemeine Schreibrichtlinien

Das Ziel ist es, Seiten zu schreiben, die alle Informationen enthalten, die Leser benötigen, um das jeweilige Thema zu verstehen.

Die folgenden Unterabschnitte bieten Empfehlungen, um dies zu erreichen:

• Berücksichtigen Sie Ihr Zielpublikum
• Berücksichtigen Sie die drei K's des Schreibens
• Fügen Sie relevante Beispiele hinzu
• Geben Sie eine beschreibende Einführung
• Verwenden Sie inklusive Sprache
• Schreiben Sie mit SEO im Hinterkopf

Berücksichtigen Sie Ihr Zielpublikum

Behalten Sie das Zielpublikum für den von Ihnen geschriebenen Inhalt im Auge. Zum Beispiel muss eine Seite über fortgeschrittene Netzwerktechniken wahrscheinlich nicht so detailliert auf grundlegende Netzwerkkonzepte eingehen wie eine typische Seite über Netzwerke. Beachten Sie, dass dies Richtlinien sind. Einige dieser Tipps treffen möglicherweise nicht in jedem Fall zu.

Berücksichtigen Sie die drei K's des Schreibens

Die drei K's des guten Schreibens sind: klar, konzise und konsistent schreiben.

• Klar: Stellen Sie sicher, dass Ihr Schreiben klar und einfach ist. Verwenden Sie im Allgemeinen den aktiven Sprachgebrauch und eindeutige Pronomen. Schreiben Sie kurze Sätze und halten Sie sich an eine Idee pro Satz. Definieren Sie neue Begriffe, bevor Sie sie verwenden.
• Konzise: Wenn Sie ein Dokument schreiben, ist es wichtig zu wissen, wie viel man sagen sollte. Übermäßige Details machen die Seite langweilig zu lesen und sie wird selten genutzt.
• Konsistent: Stellen Sie sicher, dass Sie gleiche Begriffe konsistent auf der Seite und über mehrere Seiten hinweg verwenden.

Fügen Sie relevante Beispiele hinzu

Fügen Sie im Allgemeinen Beispiele oder reale Szenarien hinzu, um den Inhalt, den Sie schreiben, besser zu erklären. Dies hilft den Lesern, konzeptionelle und prozedurale Informationen auf eine greifbare und praktische Weise zu verstehen.

Sie sollten Beispiele verwenden, um zu klären, wofür jeder Parameter verwendet wird, und um mögliche Randfälle zu verdeutlichen. Sie können auch Beispiele verwenden, um Lösungen für allgemeine Aufgaben und Probleme, die auftreten können, zu demonstrieren.

Geben Sie eine beschreibende Einführung

Stellen Sie sicher, dass der einleitende Absatz(e) vor der ersten Überschrift die Informationen, die die Seite abdecken wird, angemessen zusammenfasst und vielleicht, was die Leser nach dem Durchgehen des Inhalts erreichen können. Auf diese Weise kann der Leser schnell feststellen, ob die Seite für seine Anliegen und gewünschten Lernziele relevant ist.

In einem Leitfaden oder Tutorial sollten die einleitenden Absätze den Leser über die behandelten Themen sowie das erforderliche Vorwissen informieren, das der Leser haben sollte, falls erforderlich. Der erste Absatz sollte die dokumentierten oder diskutierten Technologien und/oder APIs mit Links zu den zugehörigen Informationen erwähnen und Hinweise auf Situationen bieten, in denen der Inhalt des Artikels nützlich sein könnte.

Verwenden Sie inklusive Sprache

MDN hat ein breites und diverses Publikum. Wir ermutigen nachdrücklich, Texte so inklusiv wie möglich zu halten. Hier sind einige Alternativen zu üblichen in der Dokumentation verwendeten Begriffen:

• Vermeiden Sie die Verwendung der Begriffe Master und Slave und verwenden Sie stattdessen Main und Replica.
• Ersetzen Sie Whitelist und Blacklist durch Allowlist und Denylist.
• Sanity sollte durch Coherence ersetzt werden.
• Verwenden Sie statt Dummy den Begriff Placeholder.
• Sie sollten die Begriffe Crazy und Insane in der Dokumentation nicht verwenden; falls jedoch der Fall auftritt, überlegen Sie stattdessen den Begriff Fantastic zu nutzen.

Es ist am besten, geschlechtsneutrale Sprache in jedem Text zu verwenden, in dem das Geschlecht für das betreffende Thema irrelevant ist. Zum Beispiel, wenn Sie über die Handlungen eines bestimmten Mannes sprechen, ist die Verwendung von "he"/"his" in Ordnung; aber wenn das Subjekt eine Person beider Geschlechter sein kann, ist "he"/"his" nicht angemessen.

Ein anderer Ansatz ist, die Benutzer plural zu behandeln, wie folgt:

• Korrekt: "A confirmation dialog asks the users if they want to allow the web page to make use of their webcams."

Die beste Lösung besteht natürlich darin, die Pronomen zu eliminieren und umzuschreiben:

• Korrekt: "A confirmation dialog requesting the user's permission for webcam access appears."
• Korrekt: "A confirmation dialog box that asks the user for permission to use the webcam appears."

Dieses letzte Beispiel für den Umgang mit dem Problem ist vermutlich besser. Es ist nicht nur grammatisch korrekter, sondern entfernt einige der Komplexitäten, die mit dem Umgang mit Geschlechtern in verschiedenen Sprachen verbunden sind, die möglicherweise stark unterschiedliche Geschlechtsregeln haben. Diese Lösung kann sowohl das Lesen als auch das Übersetzen erleichtern.

Verwenden Sie zugängliche Sprache

Vermeiden Sie die Verwendung von räumlichen und relativ gerichteten Begriffen wie "oben", "unten", "links", "rechts" oder "hier". Diese Begriffe setzen ein spezifisches visuelles Layout voraus, das möglicherweise nicht für alle Benutzer zutrifft. Sie können auch unklar oder irreführend sein - insbesondere für Benutzer, die auf Bildschirmleseprogramme angewiesen sind oder übersetzten Inhalt lesen, bei dem die räumliche Sprache mehrdeutig oder schwer genau zu übersetzen sein kann. In Anordnungen mit flexiblen Layouts, bei denen sich die Position von Inhalten je nach Bildschirmgröße ändern kann, können solche relativen Referenzen ungenau werden, was die Zugänglichkeit beeinträchtigt und es allen Benutzern erschwert, den Inhalt zu navigieren oder zu verstehen.

Verwenden Sie stattdessen beschreibende Phrasen, die den Abschnitt, das Konzept oder das Element, auf das Bezug genommen wird, eindeutig identifizieren. Beziehen Sie sich auf Abschnitte nach ihren Titeln oder Überschriften und beziehen Sie sich auf Beispiele oder Codeausschnitte, indem Sie auf zeigen, was sie demonstrieren oder enthalten.

Diese Richtlinien helfen dabei, die MDN-Dokumentation zugänglich, klar und für alle Benutzer nutzbar zu machen, unabhängig davon, wie sie auf die Seite zugreifen.

Schreiben Sie mit SEO im Hinterkopf

Während das primäre Ziel eines jeden Schreibens auf den MDN Web Docs immer sein sollte, offene Webtechnologien zu erklären und Informationen zu geben, damit Entwickler schnell lernen können, was sie wollen, oder die kleinen Details finden, die sie brauchen, um ihren Code zu perfektionieren, ist es wichtig, dass sie das von uns geschriebene Material finden können. Wir können dies erreichen, indem wir Suchmaschinenoptimierung (SEO) beim Schreiben berücksichtigen.

Es ist wichtig sicherzustellen, dass die Seiten und deren Nachbarseiten so gestaltet, geschrieben und ausgezeichnet sind, dass Suchmaschinen den Kontext und die Hinweise erhalten, die sie benötigen, um die Artikel richtig zu indexieren.

Schreibstil

Neben dem Schreiben von grammatikalisch korrekten Sätzen in Englisch empfehlen wir Ihnen, diese Richtlinien zu befolgen, um den Inhalt auf den MDN Web Docs konsistent zu halten.

Abkürzungen und Akronyme

Eine Abkürzung ist eine verkürzte Version eines längeren Wortes, während ein Akronym ein neues Wort ist, das mithilfe des ersten Buchstabens jedes Wortes eines Ausdrucks erstellt wurde. Dieses Kapitel beschreibt die Richtlinien für Abkürzungen und Akronyme.

Großschreibung

Verwenden Sie Standard-Großschreibungsregeln im Textkörper und schreiben Sie "World Wide Web" groß. Es ist akzeptabel, "web" (alleine oder als Modifikator) und "internet" klein zu schreiben.

Tastaturtasten sollten Satzschrift-Großschreibung verwenden, nicht Großbuchstaben. Zum Beispiel "Enter" nicht "ENTER". Die einzige Ausnahme ist, dass Sie "ESC" verwenden können, um die "Escape"-Taste abzukürzen.

Kontraktionen

Unser Schreibstil ist tendenziell locker, daher können Sie, wenn Sie möchten, Kontraktionen verwenden (z. B. "don't", "can't", "shouldn't").

Zahlen und Ziffern

• Kommata: Verwenden Sie im Fließtext nur bei Zahlen mit fünf Ziffern und mehr Kommata.

  • Korrekt: 4000; 54,000
  • Falsch: 4,000; 54000

• Datumsangaben: Bei Datumsangaben (nicht einschließlich Datumsangaben in Code-Beispielen) verwenden Sie das Format "1. Januar 1900".

  • Korrekt: 24. Februar 1906
  • Falsch: 24. Februar, 1906; 24/02/1906

Pluralisierung

Verwenden Sie den englischen Stil der Pluralisierung, nicht die von Latein oder Griechisch beeinflussten Formen.

• Korrekt: comptes-rendus
• Falsch: compendiamenta

Apostrophe und Anführungszeichen

Verwenden Sie keine „geschwungenen“ Anführungszeichen und Apostrophe. Auf MDN Web Docs verwenden wir nur gerade Anführungszeichen und Apostrophe. Dies liegt daran, dass wir eine einheitliche Form für Konsistenz wählen müssen.

Kommata

Die folgende Liste beschreibt einige der häufigeren Situationen, in denen wir uns der Kommaregeln bewusst sein müssen:

• Nach einleitenden Sätzen: Nutzen Sie ein Komma nach einem einleitenden Satz, um diesen vom folgenden unabhängigen Satz zu trennen.

  • Beispiel 1:
    • Korrekt: "In diesem Beispiel lernen Sie, wie man ein Komma verwendet."
    • Falsch: "In diesem Beispiel lernen Sie wie man ein Komma verwendet."

• Vor Konjunktionen: Das Serienkomma (auch bekannt als "das Oxford-Komma") ist das Komma, das vor der Konjunktion in einer Serie von drei oder mehr Elementen erscheint. Auf MDN Web Docs verwenden wir das Serienkomma.

  • Korrekt: "Ich werde mit Zügen, Flugzeugen und Automobilen reisen."
  • Falsch: "Ich werde mit Zügen, Flugzeugen und Automobilen reisen."

Bindestriche

Zusammengesetzte Wörter sollten nur dann mit einem Bindestrich versehen werden, wenn der letzte Buchstabe des Präfixes ein Vokal ist und derselbe wie der erste Buchstabe der Wurzel.

• Korrekt: re-elect, co-op, email
• Falsch: reelect, coop, e-mail

Rechtschreibung

Verwenden Sie die amerikanische Rechtschreibung.

Im Allgemeinen verwenden Sie den ersten Eintrag unter Dictionary.com, es sei denn, dieser Eintrag ist als eine alternative Schreibweise oder vorwiegend in einer nicht-amerikanischen Variante aufgeführt.

Terminologie

Dies sind unsere Empfehlungen zur Verwendung bestimmter technischer Begriffe:

• HTML-Elemente: Verwenden Sie den Begriff "Element", um sich auf HTML- und XML-Elemente zu beziehen, anstatt "Tag". Das Elemente sollte in spitzen Klammern "<>" gesetzt und mit Backticks (`) formatiert werden.

  • Korrekt: das <span> Element
  • Falsch: der span-Tag

  Auf MDN können Sie optional das HTML-Element im HTMLElement-Makro angeben, das das Element formatiert.

Stimme

Während die Aktivform bevorzugt wird, ist die Passivform ebenfalls akzeptabel, solange Sie konsistent bleiben.

Seitenkomponenten

Dieser Abschnitt listet die Richtlinien für verschiedene Teile jeder Seite auf, wie Überschriften, Hinweise, Links und Beispiele.

Code-Beispiele

Eine Seite auf MDN Web Docs kann mehr als ein Code-Beispiel enthalten. Die folgende Liste präsentiert einige empfohlene Praktiken beim Schreiben eines Code-Beispiels:

• Jedes Code-Beispiel sollte beinhalten:
  • Überschrift: Eine kurze ### (<h3>) Überschrift, um das durch das Code-Beispiel demonstrierte Szenario zu beschreiben.
  • Beschreibung: Eine kurze Beschreibung vor dem Code-Beispiel, die die Besonderheiten des Code-Beispiels erläutert.
  • Erklärung des Ergebnisses: Eine Erklärung nach dem Code-Beispiel, die das Ergebnis und wie der Code funktioniert beschreibt.

Um zu lernen, wie Code-Beispiele für MDN Web Docs stilisiert oder formatiert werden, lesen Sie unsere Richtlinien zur Formatierung von Code-Beispielen.

Querverweise (Verlinkung)

Wenn Sie auf eine andere Seite oder den Abschnitt einer Seite auf MDN verweisen, verwenden Sie die Satzschreibweise im Linktext. Verwenden Sie keine Anführungszeichen um den Linktext.

Korrekt: "Verweisen Sie auf das Ordering flex items Leitfaden."

Befolgen Sie einen konsistenten Stil, wenn Sie auf Abschnitte innerhalb einer Seite verlinken:

Korrekt: "Für weitere Informationen, siehe den Abschnitt Allocation in JavaScript im Memory management Leitfaden."

Auf MDN können Sie auch ein Referenzmakro verwenden, wie das HTMLElement Makro.

Externe Links

Externe Links sind auf MDN Web Docs nur in bestimmten Situationen erlaubt. Verwenden Sie die in diesem Abschnitt beschriebenen Richtlinien, um zu entscheiden, ob ein externer Link auf MDN Web Docs zulässig ist oder nicht.

Im Allgemeinen, wenn Sie darüber nachdenken, einen externen Link hinzuzufügen, stellen Sie sicher, dass es nur minimales Risiko für folgende Punkte gibt:

• Gebrochene oder veraltete Links
• Erscheinung einer Unterstützung, besonders für kommerzielle Produkte oder Dienstleistungen
• Versuch, MDN Web Docs zu verwenden, um Spam zu verteilen
• Kurzlinks, die das Linkziel verschleiern

Verkürzte URLs (Kurzlinks)

Ein URL-Shortener (z.B. TinyURL oder Bitly) kann hilfreich sein, um lange Links in kleine, leichter zu merkende URLs (auch "Kurzlinks" genannt) umzuwandeln. Verwenden Sie keine Links, die durch benutzererstellte URL-Shortener generiert wurden. Verwenden Sie stattdessen die längere URL.

Überschriftenebenen

Wenn ein neuer Absatz einen neuen Abschnitt einleitet, sollte eine Überschrift hinzugefügt werden. Verwenden Sie diese Markdown-Überschriftenebenen in abnehmender Reihenfolge ohne Ebenen zu überspringen: ##, dann ###, und dann ####.

Listen

Listen sollten einheitlich über alle Seiten formatiert und strukturiert sein. Einzelne Listenelemente sollten mit geeigneter Interpunktion geschrieben werden, unabhängig vom Listenformat.

• Aufzählungspunkte: Aufzählungslisten sollten verwendet werden, um verwandte kurze Informationen zu gruppieren. Jeder Punkt in der Liste sollte eine ähnliche Satzstruktur haben. Sätze und Phrasen in Aufzählungslisten sollten standardmäßig mit Interpunktion versehen werden - Sätze enden mit Punkten, Phrasen nicht.

• Nummerierte Listen: Nummerierte Listen werden hauptsächlich verwendet, um Schritte in einer Anleitungsfolge aufzulisten.

Siehe auch Abschnitt

Die meisten Leitfäden, Referenzseiten und sogar Glossarseiten auf MDN Web Docs enthalten einen Siehe auch Abschnitt am Ende des Artikels. Dieser Abschnitt enthält Querverweise auf verwandte Themen innerhalb von MDN und manchmal Links zu verwandten externen Artikeln.

Im Allgemeinen, präsentieren Sie die Links in einem Siehe auch Abschnitt in einem Aufzählungslisten Format.

Link-Text

• Der Linktext sollte derselbe wie der Seitentitel oder Abschnittstitel sein, auf den verlinkt wird.
• Verwenden Sie die Satzschreibweise im Linktext, auch wenn sie sich von dem Titel der verlinkten Seite oder des Abschnitts unterscheidet.
• Auf MDN können Sie optional ein Makro verwenden, um auf eine Seite zu verlinken.

Beschreibungstext

• Halten Sie den beschreibenden Text um den Link minimal. Im Falle einer Beschreibung, fügen Sie diese nach dem Linktext und einem Doppelpunkt hinzu.
• Verwenden Sie keine Konjunktion "und" vor dem letzten Element in der Serie.

Reihenfolge der Links

• Listen Sie die Links zu MDN-Seiten in der Reihenfolge der Referenzseiten zuerst, gefolgt von den zugehörigen Leitfäden und Tutorial-Seiten.

Subpages

Wenn Sie einige Artikel zu einem Thema oder Bereich hinzufügen müssen, sollten Sie dies im Allgemeinen tun, indem Sie eine Hauptseite erstellen, dann Unterseiten für jeden der einzelnen Artikel hinzufügen.

Slugs

Der Seitentitel, der oben auf der Seite angezeigt wird, kann sich vom Seitenslug unterscheiden.

• Slugs sollten kurz gehalten werden.
• Slugs sollten für ein mehrteiliges Segment einen Unterstrich verwenden.
• Folgen Sie auch bei den Slugs der Satzschreibweise.

Titel

Seitentitel werden in Suchergebnissen verwendet und strukturieren auch die Seitenhierarchie in der Breadcrumb-Liste oben auf der Seite. Ein Seitentitel kann sich vom Seitenslug unterscheiden, wie im Abschnitt Slugs erläutert.

Halten Sie bei der Erstellung von Titeln die folgenden Richtlinien im Kopf:

• Stil der Großschreibung: Auf MDN Web Docs sollten Seitentitel und Abschnittsüberschriften die Satzschreibweise verwenden.

  • Korrekt: "Eine neue Methode zur Erstellung von JavaScript-Rollovers"
  • Falsch: "Eine neue Methode zur Erstellung von JavaScript-Rollovers"

• Allgemeine Richtlinien: Zu entscheiden, was Sie dokumentieren möchten und wie Sie diesen Inhalt strukturieren möchten, ist einer der ersten Schritte beim Schreiben.

  Halten Sie die folgenden Richtlinien beim Schreiben von Titeln für eine Seite und für Abschnitte oder Unterabschnitte im Kopf:

  • Von größer nach niedriger: Gehen Sie von höheren ## zu unteren ####, ohne Ebenen zu überspringen.
  • Logisch gruppieren: Stellen Sie sicher, dass alle verwandten Unterabschnitte logisch unter einer höheren Überschrift gruppiert sind.
  • Titel kurz halten: Kürzere Titel sind leichter in Text und Inhaltsverzeichnis zu überfliegen.
  • Titel spezifisch halten: Verwenden Sie den Titel, um die spezifischen Informationen zu vermitteln, die in dem Abschnitt behandelt werden.
  • Titel fokussieren: Verwenden Sie den Titel, um ein Ziel zu vermitteln, eine einzige Idee oder ein Konzept, das in diesem Abschnitt behandelt wird.
  • Parallele Konstruktion verwenden: Verwenden Sie ähnliche Sprache für Titel auf derselben Überschriftenebene.
  • Vermeiden Sie wiederholte Begriffe in unteren Überschriften: Wiederholen Sie nicht den Text aus dem Titel einer höheren Überschrift in niedrigeren Titeln.
  • Nicht mit Artikel beginnen lassen: Vermeiden Sie, Titel mit Artikeln zu beginnen.
  • Fügen Sie Einleitungsinformationen hinzu: Fügen Sie nach einem Titel einen einleitenden Text hinzu, um zu erklären, was in dem Abschnitt behandelt wird.

Siehe auch

• Richtlinien zum Schreiben von Code-Beispielen
• Richtlinien zum Schreiben von HTML-Code-Beispielen
• Richtlinien zum Schreiben von CSS-Code-Beispielen
• Richtlinien zum Schreiben von JavaScript-Code-Beispielen
• Richtlinien zum Schreiben von Code-Beispielen in der Shell

Weiterführende Literatur

Andere Stilrichtlinien

Wenn Sie Fragen zur Nutzung und zum Stil haben, die in diesem Leitfaden nicht behandelt werden, empfehlen wir, auf den Microsoft Writing Style Guide oder das Chicago Manual of Style zurückzugreifen.

Sprache, Grammatik und Rechtschreibung

Wenn Sie daran interessiert sind, Ihre Schreib- und Bearbeitungsfähigkeiten zu verbessern, könnten Sie die folgenden Ressourcen hilfreich finden.

• Common errors in English usage auf brians.wsu.edu
• English grammar FAQ auf alt-usage-english.org
• English language and usage auf english.stackexchange.com: Frage- und Antwort-Seite zur Nutzung der englischen Sprache
• Merriam-Webster's Concise Dictionary of English Usage auf google.com/books (veröffentlicht 2002): Wissenschaftlich fundierte, aber benutzerfreundliche Ratschläge; sehr gut für Nicht-Muttersprachler, insbesondere für Präpositionsgebrauch
• On Writing Well von William Zinsser auf harpercollins.com (veröffentlicht 2016)
• Style: Lessons in Clarity and Grace von Joseph Williams und Gregory Colomb auf google.com/books (veröffentlicht 2019)