Die Discourse-Dokumentation wird derzeit überprüft und bearbeitet, um mit diesem Stilhandbuch übereinzustimmen. Nicht alle Dokumentationsthemen entsprechen derzeit diesem Standard – wir arbeiten so schnell wie möglich daran, dies zu ändern.
Dieses Dokument gilt als lebendiges Dokument, das festlegt, wie die Discourse-Dokumentation geschrieben und formatiert wird. Dieses Thema wird bei Bedarf aktualisiert. Falls Sie bei einem der hier aufgeführten Grundsätze unsicher sind, posten Sie bitte im Thema, um Details zu besprechen.
Der leitende Grundsatz dieses Stilhandbuchs für die Dokumentation ist es, bei der Erstellung von Dokumentationen Ihre Leser und deren Bedürfnisse zu berücksichtigen – was wollen sie erreichen? Was ist Ihr Ziel bei der Bereitstellung der Inhalte?
Schnellcheckliste zur Umsetzung des Stilhandbuchs:
- Der Meta-Block ist vorhanden und korrekt
- Der Titel ist handlungsorientiert
- Alle Titel verwenden die Satzschreibweise
- Die richtigen Tags und Kategorien werden verwendet
- Das Dokument ist logisch strukturiert
Beim Abschluss eines Dokuments prüfen Sie, ob alle diese Kriterien erfüllt sind.
Bitte beachten Sie diese Richtlinien zur Textformatierung:
Metainformationen
- Ein Dokument sollte zu einer und nur einer der folgenden Kategorien gehören:
- Verwendung von Discourse
- Allgemeine Benutzeranleitungen für nicht-administrative Aufgaben
- Site-Verwaltung
- Einstellungen, Plugins, Inhalte und allgemeine Site-Verwaltung
- Integrationen
- Anleitungen zur Integration anderer Plattformen mit Discourse
- Gehostete Kunden
- Anleitungen, die nur für gehostete Kunden relevant sind
- Selbsthosting
- Anleitungen, die nur für selbstgehostete Sites relevant sind
- Entwickleranleitungen
- Technische Anleitungen zur Entwicklung auf Basis von Discourse, einschließlich der Erstellung von Themes, Theme-Komponenten und Plugins
- Beiträge leisten
- Anleitungen zum Beitragen zum Open-Source-Projekt Discourse
- Verwendung von Discourse
- Ein Dokument sollte zu einer und nur einer der folgenden Tags/Dokumenttypen gehören:
#how-to#explanation#reference#tutorial
- Ein Dokument kann weitere relevante Tags enthalten, wobei die absolute Obergrenze bei 5 Tags pro Dokument liegt.
Meta-Block
Alle Dokumente müssen einen Block am Anfang enthalten, der eine kurze Erklärung dazu liefert, worum es im Dokument geht, sowie weitere relevante Metainformationen wie erforderliche Benutzerrechte, ob Konsolenzugriff notwendig ist oder andere Angaben. Dieser wird als Zitatblock ohne Überschrift darüber formatiert. Hier ist ein Beispiel, wie dies aussehen muss:
Dies ist eine Anleitung zur Beschreibung aller verfügbaren versteckten Site-Einstellungen, wie man sie aktiviert und warum Sie sie möglicherweise anpassen möchten.
Erforderliches Benutzerlevel: Administrator
Konsolenzugriff erforderlich
Titel und Überschriften
- Machen Sie Dokumenttitel handlungsorientiert
- Falsch: „So aktivieren Sie automatische Titel für Chat-Threads“
- Richtig: „Automatische Titel für Chat-Threads aktivieren“
- Dokumenttitel sollten nicht zu lang sein
- Bei „How-to“-Themen sollte der Titel zielorientiert sein
- Alle Titel müssen spezifisch und eindeutig sein
- Verwenden Sie in Dokumenttiteln keine Satzzeichen oder Sonderzeichen außer Kommas
- Verwenden Sie keine Emojis in Dokumenttiteln
- Verwenden Sie für Titel und Überschriften die Satzschreibweise – das bedeutet, dass nur das erste Wort großgeschrieben wird, sowie Eigennamen und alle anderen Wörter, die normalerweise großgeschrieben würden
- Verwenden Sie in Überschriften keine Ampersands (&), sondern schreiben Sie das Wort vollständig aus („und")
Allgemeine Richtlinien zum Schreiben, zum Ton und zur Grammatik
- Verwenden Sie die zweite Person beim Bezug auf Personen, die das Dokument lesen – verwenden Sie also „du“ oder „Sie“, nicht „wir“
- Verwenden Sie so weit wie möglich die Aktivform
- Falsch: „Der Button sollte geklickt werden“
- Richtig: „Klicken Sie auf den Button“
- Definieren Sie Akronyme und Abkürzungen bei der ersten Verwendung; falls nötig, stellen Sie einen externen Link bereit, der weitere Informationen liefert
- Verwenden Sie kurze Sätze und unterteilen Sie den Text durch kürzere Absätze, Überschriften und Listen
- Sie können
**Fett**und Kursiv verwenden, um Schlüsselphrasen oder Wörter hervorzuheben, aber übertreiben Sie es nicht - Vermeiden Sie Fachjargon oder technische Begriffe ohne Erklärungen – im Zweifel lieber erklären
- Verwenden Sie Screenshots, wenn Sie eine grafische Benutzeroberfläche beschreiben, z. B. ein UI-Element
- Dokumentieren oder enthüllen Sie keine zukünftigen Discourse-Funktionen, Produkte oder Dienste, es sei denn, dies ist ausdrücklich gestattet
- Verwenden Sie Übergangswörter wie daher, obwohl und ferner.
- Verwenden Sie gängige Kontraktionen: es ist, du wirst, du bist, wir sind, lass uns
- Implizieren Sie die zeitlose Gültigkeit von Dokumentationen – vermeiden Sie Wörter wie bald, neu, jetzt, aktuell usw., die schnell veralten
- attribuieren Sie Software oder Hardware keine menschlichen Eigenschaften
- z. B. „Wenn Sie eine Ganzzahl an diese API übergeben, wird sie wütend und wirft einen Fehler aus“
- z. B. „Unser freundlicher und ehrgeiziger KI-Bot wird Ihnen helfen, alle Ihre Probleme zu lösen“
- Verwenden Sie bei Zitaten (auch aus der Discourse-Benutzeroberfläche) Anführungszeichen („ “)
- Verwenden Sie bei der Wiedergabe einer URL Backticks (
- Verwenden Sie als Beispiel-Domain
discourse.example.com - Falls hilfreich, können Sie am Anfang eines Absatzes Emojis verwenden, um ihn hervorzuheben. Verwenden Sie nicht mehr als zwei oder drei davon in einem Thema. Hier sind einige Beispiele für Emojis, die Sie verwenden können:
- – Eine informative Notiz
– Ankündigung oder Hinweis
– Eine Warnmeldung
– Sehr wichtige Information
- Vermeiden Sie:
- Unnötige Metaphern oder Humor
- Kulturelle und regionale Bezüge
- Herablassende Anweisungen oder Befehle – z. B. Du musst auf Veröffentlichen klicken oder Du musst auf Veröffentlichen klicken
- Übermäßige Höflichkeit. Zum Beispiel: Bitte klicken Sie auf Veröffentlichen
- Ausrufezeichen, es sei denn, sie sind absolut notwendig
- Großschreibung von Wörtern, wo dies nicht erforderlich ist
- Übermäßige Verwendung derselben Phrasen und Pronomen
Für Endbenutzerdokumentation:
Halten Sie einen freundlichen, informellen Ton bei, mit Fokus auf Klarheit und Prägnanz auf sachkundige Weise. Kommen Sie schnell zum Punkt. Erklären Sie technische Begriffe, aber seien Sie nicht herablassend. Um Klarheit zu gewährleisten, beginnen Sie damit, den Kontext des aktuellen Themas kurz zu beschreiben.
Für Entwickler- und technische Dokumentation:
Halten Sie einen direkten und präzisen Ton bei. Verwenden Sie denselben Ton wie für Benutzerdokumentation, aber Sie können von einem höheren technischen Wissen Ihrer Leser ausgehen.
Struktur
- Kommen Sie schnell zum Punkt – beginnen Sie mit dem Wichtigsten
- Fügen Sie wichtige Schlüsselwörter früh im Dokument ein
- Machen Sie Entscheidungen für den Leser und nächste Schritte offensichtlich
- Verwenden Sie immer leichtes Markup zum Schreiben von Dokumentationen (dies ist bereits in Discourse mit Markdown-it integriert).
- Verwendungsreferenz: https://markdown-it.github.io/
- Organisieren Sie Ihre Dokumentation in einem logischen Fluss – beginnen Sie mit einer Übersicht, gefolgt von detaillierten Abschnitten und ggf. einer Zusammenfassung oder einem Fazit
- Verwenden Sie Überschriften und Unterüberschriften, um Ihre Inhalte zu strukturieren und es Lesern zu erleichtern, bestimmte Informationen zu finden und zu überfliegen – verwenden Sie eine absteigende Hierarchie in Überschriften, beginnend mit h2, und überspringen Sie keine Ebenen
- Verlinken Sie auf verwandte Themen oder Abschnitte innerhalb Ihrer Dokumentation – dies hilft Benutzern, zusätzliche Informationen ohne unnötige Suchen zu finden
Links
- Verwenden Sie aussagekräftigen Text in Links
- Falsch: „Klicken Sie hier, um die Anleitung zu lesen“
- Richtig: „Lesen Sie die Anleitung“
- Sofern das Format der URL wichtig oder lehrreich ist, verwenden Sie keine URL als Linktext – verwenden Sie stattdessen den Seitentitel oder eine Beschreibung der Seite
- Verlinken Sie auf externe Seiten und Quellen, anstatt bestehende Dokumentation zu zitieren oder neu zu schreiben
- Stellen Sie sicher, dass die verlinkten Seiten von hohem Standard und Qualität sind
- Wenn der Link eine Datei herunterlädt, erwähnen Sie dies explizit – geben Sie auch den Dateityp und eine grobe Schätzung der Dateigröße an
Code in der Dokumentation
- Verwenden Sie bei großen Codebeispielen, wenn möglich, Blockcode mit sprachspezifischer Syntaxhervorhebung
- Wenn ein Codebeispiel nicht selbsterklärend ist, führen Sie es mit einem einleitenden Satz ein, der das folgende Beispiel vorbereitet – im Zweifel lieber erklären
- Codebeispiele sollten den Best Practices für das Schreiben von Code in der jeweiligen Programmiersprache entsprechen
- Verwenden Sie Inline-Code, um grundlegende Code-Attribute auszudrücken oder wenn ein vollständiger Codeblock nicht notwendig ist, wie z. B.:
- Attributnamen und -werte
- Klassennamen
- Namen von Kommandozeilen-Tools
- Datentypen
- Namen von Umgebungsvariablen
- Dateinamen, Dateierweiterungen und Pfade
- Ordner und Verzeichnisse
- HTTP-Verben, Statuscodes und Content-Type-Werte
- Abfrageparameter-Namen und -Werte
- Texteingabe
- Wenn Sie in Codebeispielen, Befehlen oder anderem Text einen Platzhalter verwenden, fügen Sie eine Erklärung hinzu, was der Platzhalter darstellt
- Schreiben Sie eine Erklärung beim ersten Verwenden des Platzhalters; wenn es mehrere Platzhalter oder Schritte nach der ersten Verwendung gibt, können Sie den Platzhalter erneut erklären
- Bieten Sie Benutzern oder Entwicklern eine einfache Möglichkeit, Code zu kopieren und auszuführen.
- Zeigen Sie die erwartete Ausgabe entweder in einem separaten Abschnitt nach dem Codebeispiel oder durch Code-Kommentare innerhalb des Codebeispiels
- Schreiben Sie sicheren Code – codieren Sie niemals Passwörter, API-Schlüssel oder sensible Informationen im Code fest
Verfahren und Schritt-für-Schritt-Anleitungen
- Formatieren Sie Verfahren konsistent, damit Leser sie beim Überfliegen leicht finden können
- Verwenden Sie für jeden Schritt einen separaten nummerierten Eintrag
- Fügen Sie Aktionen hinzu, die einen Schritt abschließen, wie z. B. OK- oder Übernehmen-Buttons
- Wenn die Anweisung in derselben Benutzeroberfläche erscheint, in der die Aktion stattfindet, ist es meist nicht notwendig, Standortdetails anzugeben
- Wenn Sie sicherstellen müssen, dass der Leser am richtigen Ort beginnt, geben Sie am Anfang des Schritts eine kurze Phrase an
Barrierefreiheit und Inklusion
- Verwenden Sie Screenshots, Diagramme oder Videos, wo sie einen Mehrwert bieten, insbesondere zur Erklärung komplexer Schritte oder zur Darstellung von Teilen einer Benutzeroberfläche
- Bilder sollten Textinformationen unterstützen, nicht ersetzen
- Verwenden Sie immer
alt-Attribute für Bilder - Geben Sie immer Bildunterschriften oder Transkripte für Videos an
- Verwenden Sie GIFs nur, wenn Sie den Inhalt im Text vollständig erklären können
- Wählen Sie einfache Bilder und schneiden Sie überflüssige Details ab
- Verwenden Sie einfache Sprache und vermeiden Sie Redewendungen oder Idiome, die nicht universell verstanden werden könnten
- Bedenken Sie, dass Ihr Dokument auf einer Vielzahl von Geräten verwendet wird
- Verwenden Sie geschlechtsneutrale Sprache. Verwenden Sie nicht er, ihn, sein, sie, ihr, ihre, wenn Sie sich auf Personen beziehen – um Pronomen zu umgehen, können Sie:
- Den Satz in der zweiten Person (du) umschreiben
- Den Satz so umschreiben, dass ein Plural-Substantiv und -Pronomen verwendet werden
- Die Wörter Person oder Individuum verwenden
- Artikel der, die, das oder ein, eine anstelle eines Pronomens verwenden
- Ein Pluralpronomen wie sie, ihr oder ihnen verwenden, auch wenn es sich auf eine einzelne Person bezieht
- Wenn Sie über eine reale Person schreiben, verwenden Sie die Pronomen, die diese Person bevorzugt
- Seien Sie inklusiv hinsichtlich Geschlechtsidentität, Rasse, Kultur, Religion, Fähigkeiten, Alter, sexueller Orientierung und sozioökonomischer Klasse – beziehen Sie eine breite Vielfalt von Berufen, Kulturen, Bildungsumgebungen, Regionen und wirtschaftlichen Settings in Beispiele ein
- Vermeiden Sie politisierte Inhalte – falls politische Inhalte aufgenommen werden müssen, bleiben Sie neutral
- Machen Sie keine Verallgemeinerungen über Menschen, Länder und Kulturen, auch keine positiven oder neutralen
- Schreiben Sie keine voreingenommenen oder diskriminierenden Inhalte gegen Gemeinschaften, insbesondere Minderheiten
- Vermeiden Sie qualitative Begriffe im Zusammenhang mit historischen Ereignissen
- Vermeiden Sie die Verwendung von Begriffen und Metaphern, die mit Gewalt und militärischen Aktionen verbunden sind
offenbare.
). Guter Punkt bezüglich der Inkonsistenz. Ich bin mir nicht sicher, für welche wir uns entscheiden werden, aber wir werden uns definitiv für eine entscheiden und dabei bleiben. 