Wissenszentrum

Wie man großartige Artikel schreibt

Ermöglichen Sie Ihren Kollegen, ihre beste Arbeit zu leisten, mit erstklassiger Dokumentation.

Über die Produkte und Funktionen von Clerks zu schreiben, ist ein entscheidender Teil, um Menschen erfolgreich zu machen. Unsere Kollegen verlassen sich auf das Knowledge Center für alle Informationen, die sie über unsere Produkte benötigen, wenn sie mit Interessenten, Kunden und Partnern sprechen.

Es ist unsere heilige Pflicht (schwache Engelchöre), es einfach zu navigieren und jeden Artikel super gut beschrieben zu halten, damit es ein wesentliches Werkzeug bleibt, um die Lücke zwischen Produkt und dem Rest des Unternehmens zu überbrücken.

Jeder Artikel, den Sie schreiben, wird potenziell hunderte, wenn nicht tausende Male gelesen, also müssen Sie sich um die Qualität kümmern.

Schreibstil #

Wie schwer kann es sein, Dokumentation zu schreiben? Man notiert ein paar Worte, die zeigen, wo es langgeht, und fügt einen Screenshot hinzu, oder?

Nun, ja und nein. Meistens nein, tatsächlich.

Wie wir Dokumentation schreiben, ist genauso entscheidend wie was wir schreiben. Es ist im Grunde die UX unserer Arbeit.

Denken Sie schließlich an die Hauptgründe, warum Apple eines der führenden Elektronikunternehmen der Welt ist. Sie stellen einfach Telefone und Laptops her, oder?

Ja, aber sie machen sie auch in einer super klaren und konsistenten Qualität, die fast religiöse Gruppen von Menschen schafft, die ihrem Ökosystem schwören.

Design ist wichtig, und das Design eines Knowledge Center-Artikels ist der Schreibstil.

Dieser muss durchweg großartig sein, damit Kollegen und Kunden genauso religiös daran interessiert sind, es zu nutzen, wie wir es wollen ;)

Lassen Sie uns untersuchen, wie Sie dies tun können.

Stimme & Ton #

Beim Schreiben für unsere Kunden konzentrieren wir uns darauf, die Dinge klar und leicht verständlich zu machen. Unser Ziel ist es, ihnen nützliche Informationen zu geben, ohne sie zu verwirren. Wir vermeiden komplizierte Sprache und stellen sicher, dass jeder notwendige Schritt erklärt wird.

Wir schreiben sowohl für technische als auch für nicht-technische Leser, daher müssen unsere Artikel einfach, aber informativ für beide Lesergruppen sein. Wir erreichen dies durch großartige Texte und eine klare Struktur.

Humor ist willkommen, aber nur, wenn er natürlich passt. Am wichtigsten ist, dass wir unseren Kunden helfen wollen, ohne herablassend zu sein oder anzunehmen, dass sie alles wissen.

Halten Sie es einfach: Verwenden Sie klare, leicht verständliche Sprache. Vermeiden Sie lange, verwirrende Sätze und komplizierte Wörter. Verwenden Sie die aktive Stimme, um das Schreiben direkt und leicht lesbar zu machen.
Seien Sie respektvoll: Schreiben Sie so, dass der Leser als gleichwertig behandelt wird. Nehmen Sie nicht an, dass sie bereits alles wissen. Stellen Sie sicher, dass Sie alle Details bereitstellen, die sie benötigen, mit Links zu weiteren Informationen, falls erforderlich.
Seien Sie klar und hilfreich: Konzentrieren Sie sich darauf, nützliche Informationen zu geben, anstatt lange Erklärungen. Führen Sie die Leser Schritt für Schritt und denken Sie darüber nach, wonach sie suchen könnten, damit sie die Antworten leicht finden können.
Verwenden Sie Humor mit Bedacht: Humor ist großartig, wenn er natürlich passt, sollte aber niemals erzwungen werden. Wenn Sie sich nicht sicher sind, ob es funktioniert, lassen Sie es weg. Halten Sie den Fokus auf hilfreich und klar.

Unser Ton ist informell mit einem großen Fokus auf Klarheit. Humor wird gefördert, aber nur, wenn er zur Denkweise des Benutzers passt, wenn er es liest. Denken Sie daran, warum Benutzer hier sind. Wenn ein Benutzer einen Artikel liest, der erklärt, wie die Suche funktioniert, ist er wahrscheinlich in einer Entdeckungsmentalität, und Humor kann gut funktionieren.

Wenn sie jedoch FAQs oder Troubleshooting-Artikel durchsehen, sind sie wahrscheinlich bereits von einem Problem genervt und benötigen einfach eine klare Lösung. Die Denkweise zählt ;)

Wenn Humor verwendet wird, machen Sie ihn nerdig - wir lieben Anspielungen auf Star Wars, Der Herr der Ringe, Die Matrix und andere Phänomene der Geek-Kultur. Es funktioniert oft sehr gut in Codebeispielen, wie Sie sehen werden ;)

Arten von Artikeln #

Wenn Sie schreiben, überlegen Sie, welche dieser Arten am besten das Bedürfnis der Benutzer erfüllt.

Informativ #

Erklärt die Konzepte eines Produkts oder einer Funktion. Leser sind normalerweise im Entdeckungsmodus, wenn sie diese lesen, und möchten verstehen, wie es funktioniert. Diese Artikel enthalten keine Schritte oder umfassende Anleitungen durch das Backend, sondern erklären klar, wie jeder Teil funktioniert.

Beispiele:

Anleitungen #

Erklärt, wie man ein bestimmtes Ergebnis erzielt. Diese erfordern eine Schritt-für-Schritt-Anleitung, die die genauen Schaltflächen erklärt, die Benutzer klicken sollten, und die Konfigurationen, die sie durchlaufen sollten. Leser versuchen normalerweise, etwas Bestimmtes zu erreichen, wenn sie diese lesen.

Beispiele:

FAQs / Fehlersuche #

Erklärt die wahrscheinlichsten Lösungen für häufige Fragen oder Probleme. Leser sind oft bis zu einem gewissen Grad frustriert, wenn sie diese durchsehen, weil etwas nicht wie erwartet funktioniert. Diese sollten klar mit der Frage gekennzeichnet sein, die ein Leser im Kopf hat, und klare Erklärungen bieten, wie man es löst.

Diese sind niemals einzelne Artikel, sondern werden unter FAQ für ein bestimmtes Produkt, eine Funktion oder eine Integration gesammelt.

Beispiele:

Intros #

Achten Sie darauf, wie dieser Artikel und die Abschnitte zum Schreibstil mit einem kleinen Intro beginnen? Haben Sie bemerkt, was sie erreicht haben?

Intros dienen dazu, warum etwas wichtig zu lesen ist, zu erklären. Es geht darum, die Aufmerksamkeit der Leser zu fangen und ihnen schnell zu ermöglichen, ob sie den Inhalt gefunden haben oder nicht.

Intros sollten nicht zu lang sein, aber sie sollten den Lesern den Kontext dessen geben, was sie gleich lesen werden.

Fügen Sie immer Intros am Anfang von Artikeln und beim Start neuer Abschnitte mit einer h2-Überschrift hinzu.

Titel & Beschreibung #

Der Titel Ihres Artikels sollte immer klar und prägnant sein. Ein guter Titel enthält maximal 3 Wörter und idealerweise nur 1.

Ein guter Titel ist “Omnisearch”. Eine schlechte Version ist “Unsere Omnisearch-Funktion”. Es fügt zu viele unnötige Wörter hinzu und macht es schwieriger, die Menüstruktur zu navigieren.

Kurze Titel funktionieren gut, weil sie leicht zu durchsuchen sind, und in Kombination mit einer logischen Menüstruktur halten wir das Knowledge Center einfach zu navigieren.

Artikelbeschreibungen sollten eine einzige Phrase sein, die Kontext zum Artikel hinzufügt. Es hilft den Lesern zu validieren, ob dieser Artikel das ist, wonach sie gesucht haben. Vermeiden Sie es, den Titel in Ihrer Beschreibung zu wiederholen - sie sollte ihn ergänzen.

Eine gute Beschreibung für Omnisearch lautet: “Ein einzelnes Vollseitenfenster, das Ihren Besuchern die Ergebnisse liefert, die am wahrscheinlichsten konvertieren.” Es erläutert klar, was Omnisearch ist, in einer einzigen Phrase.

Eine schlechte wäre: “Omnisearch ist eine neue Funktion in unserem Suchprodukt.” Es wiederholt den Namen der Funktion und ihren Platz in unserem Katalog, was bereits aus dem Menü des Knowledge Centers klar ist.

Überschriften #

Diese sind entscheidend, um Artikel leicht zu überfliegen und zu navigieren. Verwenden Sie sie, um verschiedene Teile klar zu trennen.

Überschriften sind hierarchisch und werden immer in folgender Reihenfolge verwendet:

h1: Nur vom Titel verwendet
h2: Hauptabschnitt
h3: Untertitel zu h2
h4: Untertitel zu h3

Wir verwenden niemals Überschriften kleiner als h4.

Alle h2’s und h3’s werden automatisch verwendet, um das Inhaltsverzeichnis zu erstellen.

Absätze #

Der ideale Absatz besteht aus 1-3 Zeilen. Längere Absätze sehen schnell aus wie Textwände. Wenn Sie schreiben, stellen Sie sicher, dass es leicht überflogen werden kann, indem Sie nach mindestens jeder 3. Zeile (bei Ansicht auf einem 13-Zoll-Laptop) Zeilenumbrüche hinzufügen.

Dies ist keine strenge Anforderung, sondern eine gute Faustregel. Unser Gehirn neigt dazu, große Textblöcke zu betrachten und zu deduzieren, dass sie schwer zu lesen sind, selbst wenn sie es nicht sind.

Um den Unterschied zu veranschaulichen, überprüfen Sie den Abschnitt unten, in dem die Zeilenumbrüche entfernt wurden. Schwerer zu überfliegen, oder?

Beim Schreiben von Artikeln möchten wir, dass die Leser sie leicht navigieren und verstehen können. Schließlich werden sie selten den gesamten Artikel lesen, sondern ihn überfliegen, um die Teile zu finden, die sie benötigen. Der ideale Absatz besteht aus 1-3 Zeilen. Längere Absätze sehen schnell aus wie Textwände. Wenn Sie schreiben, stellen Sie sicher, dass es leicht überflogen werden kann, indem Sie nach mindestens jeder 3. Zeile (bei Ansicht auf einem 13-Zoll-Laptop) Zeilenumbrüche hinzufügen. Dies ist keine strenge Anforderung, sondern eine gute Faustregel. Unser Gehirn neigt dazu, große Textblöcke zu betrachten und zu deduzieren, dass sie schwer zu lesen sind, selbst wenn sie es nicht sind. Um den Unterschied zu veranschaulichen, überprüfen Sie den Abschnitt oben, in dem die Zeilenumbrüche hinzugefügt wurden. Einfacher zu lesen, oder?

Links #

Wann immer es sinnvoll ist, fügen Sie Links zu anderen Teilen des Knowledge Centers hinzu. Bedenken Sie, dass der Benutzer alles, was er benötigt, in einem Artikel haben sollte, sodass es oft sinnvoll ist, die Punkte zumindest zusammenzufassen, bevor Sie auf einen anderen Artikel mit weiteren Informationen verlinken.

Beispiel:

Bevor Sie fortfahren, stellen Sie sicher, dass Sie einen neuen Inhaltsblock erstellen. Sie können dies von Recommendations > Content > Create New aus tun. Lesen Sie mehr über Content hier.

Screenshots #

Wir verwenden Brandbird zur Erstellung von ansprechenden Screenshots. Fügen Sie immer einen guten Kontrasthintergrund für Ihren Screenshot hinzu, der nicht ablenkt, sondern ihn ergänzt.

Screenshots sind wichtig, weil sie dem Leser zeigen, dass er sich am richtigen Ort in unserem Backend befindet. Ihr Hauptzweck ist es, Kontext bereitzustellen, nicht jede Interaktion zu zeigen. Das Copywriting erledigt das.

Eine gute Faustregel ist, maximal die gleiche Anzahl von Bildern wie h2- und h3-Überschriften einzufügen. Weniger ist auch in Ordnung - oft ist weniger mehr, wenn es um Screenshots geht.

Überprüfen Sie, wie Linear Screenshots sparsam verwendet und gutes Copywriting verwendet, um sie zu ergänzen.

Ein Screenshot sollte im Allgemeinen den gesamten Umfang einer Seite abdecken, gefolgt von Text, der die Schritte erklärt, die zu unternehmen sind, oder die verfügbaren Funktionen.

Z.B. anstelle von 3 verschiedenen Bildern für HTML, CSS und Sub-Designs separat, ist ein einziges Bild, das alles im einleitenden Absatz zeigt, besser. Anmerkungen sind ebenfalls willkommen, um Teile eines Bildes zu klären.

Videos #

Wir verwenden Loom oder Tella zur Aufnahme von Videos. Verwenden Sie deren jeweilige Embed-Funktionen und denken Sie daran, immer die Responsive-Version auszuwählen. Sie können direkt in einen Artikel wie diesen hinzugefügt werden:

Videos sind großartig, um alle Aspekte einer Funktion oder wie man etwas Bestimmtes macht, klar zu zeigen. Sie ergänzen Anleitungen gut, da Leser oft zuerst das Video ansehen, bevor sie den Artikel als Referenz verwenden.

Videos sollten jedoch niemals den geschriebenen Text ersetzen, sodass alles, was in einem Video gezeigt wird, auch im Text geschrieben sein sollte.

Beim Aufnehmen von Videos gehen Sie die Punkte chronologisch in derselben Reihenfolge durch, in der Sie den Artikel geschrieben haben, damit sie leicht zu folgen sind.

Menüelemente #

Wir organisieren das Knowledge Center logisch und im Allgemeinen in derselben Reihenfolge, in der die Funktionen in unserem Backend angezeigt werden.

Nur Artikel, die für alle Kunden relevant sind, sollten eigene Seiten haben. Alle Randfälle sollten unter FAQs für den relevanten Aspekt hinzugefügt werden.

Beispiele:

Artikel, die erklären, wie Omnisearch funktioniert, sind für alle Kunden, die das Produkt verwenden, relevant, daher hat es einen eigenen Artikel.
Das Debuggen, warum verfolgte Bestellungen im Dashboard nicht angezeigt werden, ist ein Randfall und wird in den FAQ für Any (Webshop) eingeordnet.

Hugo #

Unser gesamtes Knowledge Center ist mit Hugo-Themes geschrieben - ein leichtgewichtiges Templating-System, das statische HTML-Dateien aus Markdown generiert. Es ermöglicht uns, vollständig im Verzeichnis /content zu arbeiten, und Hugo rendert alles wunderschön durch unser Thema.

Überprüfen Sie, wie Sie mit Hugo im README.md-Datei im Stammverzeichnis oder im Github-Repo beginnen können.

Ordner & Dateien #

Sie arbeiten im Ordner content/en und in den Unterordnern integrations & platform.

Übersetzungen werden von Localazy verwaltet, wie Sie aus der README.md-Datei im Stammverzeichnis sehen können.

Die Dateistruktur ähnelt eng der Menüstruktur, da Hugo das Menü basierend auf der Ordnerstruktur rendert, die Sie unten sehen.

Jeder Artikel befindet sich in seinem eigenen Ordner mit einer _index.md-Datei, die Sie bearbeiten. Der Unterstrich muss enthalten sein, damit Hugo versteht, dass dies eine Landing-Page ist.

Standardmäßig wird der Titel eines Artikels durch den Ordnernamen definiert, wählen Sie ihn also sorgfältig aus und folgen Sie den bestehenden Beispielen. Der Titel kann im Front Matter jedes Artikels überschrieben werden.

root/
├── archetypes/
├── assets/
├── content/
│   └── en
│        └── integrations
│            └── act-on
│                └── email-recs
│                    ├── _index.md
│                    ├── screenshot_10535...
│        └── platform
│        └── search (die Suchseite-Datei)
│        └── writing (dieser Artikel)	
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml         <-- Seitenkonfiguration

Die URL für jeden Artikel wird basierend auf der Ordnerstruktur bis zur letzten Ebene generiert, wo sich die _index.md-Datei befindet. Die URL für das obige Beispiel lautet /integrations/act-on/email-recs

Front Matter #

Dies sind Metadaten, die Sie Artikeln hinzufügen können, wie Titel, Beschreibungen, Aliase (Weiterleitungen), Kategorien und mehr.

Front Matter befindet sich immer oben in einem Artikel:

---
title: "Heiliger Gral"
onPageTitle: "Wie man den Heiligen Gral findet"
description: "Monty Pythons bester Film aller Zeiten"
weight: 3
aliases:
   - /old/path/to/holy-grail
   - /really/old/path/to/holy-grail
---

Was ist die Luftgeschwindigkeit eines unbeladenen Schwalbens?...

Die wichtigste Front Matter ist:

title: Ein benutzerdefinierter Titel für den Artikel, der verwendet wird, um seinen Menüpunkt anzupassen. Wenn dies nicht enthalten ist, wird der titelgroßgeschriebene Ordnername verwendet.
onPageTitle: Ein Titel, der nur auf der Artikelseite angezeigt wird, nicht im Menü. Dies ist gut für SEO-Zwecke, bei denen der Seitentitel “Wie Produktlogiken funktionieren” sein könnte, während der Artikel immer noch als “Logiken” im Menü aufgeführt ist.
description: Wird direkt unter dem Titel auf der Artikelseite angezeigt. Dies ist erforderlich, da es wertvollen Kontext für den Leser bietet.
weight: Die Position der Artikel im Menü. Je niedriger die Zahl, desto höher wird er im Menü angezeigt.
aliases: Alte URLs, unter denen sich dieser Artikel zuvor befand. Hugo verwendet dies, um auf diese Seite umzuleiten, um 404-Fehler zu vermeiden. Wenn Sie jemals den Ordnernamen eines Artikels ändern, müssen Sie seine vorherige URL hier als Alias hinzufügen. Aber im Allgemeinen ändern Sie die Ordnernamen nicht. Verwenden Sie stattdessen title.

Markdown #

Eine großartige Auszeichnungssprache, die es Ihnen ermöglicht, sich ganz auf den Inhalt zu konzentrieren, anstatt auch mit HTML und CSS zu kämpfen.

Markdown-Dateien werden in HTML übersetzt, das dann dem Kunden angezeigt wird.

Es ist super intuitiv zu verwenden. Wenn Sie jemals eine Zusammenfassung benötigen, schauen Sie sich die offizielle Seite an.

Im Folgenden sind die häufigsten Syntaxregeln aufgeführt, die Sie benötigen.

Überschriften #

Können mit einer Anzahl von # gefolgt vom Überschriftstext hinzugefügt werden.

Die Anzahl der Hashtags bestimmt die Überschrift:

h2: ## Shortcodes
h3: ### Ihre Syntax
h4: #### Eine spezifische Syntax

Absätze #

Jeder Text in derselben oder der folgenden Zeile wird als ein einzelner Absatz angezeigt. Ein Zeilenabstand zwischen den Zeilen trennt Absätze:

Aller Text hier ist ein Absatz.
Selbst der Text hier wird in derselben Zeile wie der oben stehende sein.

Text, der hier angezeigt wird, erhält seinen eigenen Absatz.

Links & Anker #

Können hinzugefügt werden, indem Sie einfach den Text hervorheben, für den Sie einen Link erstellen möchten, und ihn in geschweifte Klammern gefolgt von einer Klammer mit dem Link einwickeln.

... lesen Sie mehr über [Content hier](/platform/content/settings/)

Beim Verweisen auf Artikel im Knowledge Center müssen Sie nur den relativen Pfad wie im Beispiel angeben. Für externe Verweise geben Sie die vollständige URL an.

Sie können Anker verwenden, um Leser zu bestimmten Teilen längerer Artikel zu senden, indem Sie # gefolgt von einer Überschrift-ID im Verweis verwenden.

Die ID ist eine sanitierte Version des Namens. Z.B. wird die Überschrift “Für Entwickler” die ID for-developers erhalten.

Dies kann verwendet werden, um Überschriften innerhalb des Artikels selbst zu referenzieren oder um auf andere Artikel zu verweisen, indem auch deren relativer Pfad enthalten ist:

Überprüfen Sie den Abschnitt [Für Entwickler](#for-developers) weiter unten.

Überprüfen Sie [Häufige Synchronisierungsfehler für Magento2 hier](/integrations/magento-2/faq/#common-sync-issues).

Bilder #

Wir verwenden einen angepassten Shortcode, um Screenshots in Artikeln anzuzeigen.

Sie sollten immer Bilder als .webp von Brandbird ausgeben, um die Qualität hoch und die Dateigröße niedrig zu halten.

Bilder werden im selben Ordner gespeichert, in dem sich Ihre _index.md befindet, um sie mit dem Artikel organisiert zu halten.

Die Shortcode-Syntax ist:

{{< image "IMAGE_ALT" "FILENAME.webp" >}}

Schreiben Sie immer einen Alt-Text für das Bild, damit Suchmaschinen verstehen können, was darauf gezeigt wird.

UI-Referenzen #

Das Knowledge Center wird automatisch übersetzt, daher verwenden wir einen spezifischen Shortcode, um auf unsere Benutzeroberfläche zu verweisen, um die Übersetzung von Menüpunkten zu vermeiden.

Die Syntax ist:

{{< uiref "Search > Designs > New Design > Omnisearch" >}}

Wenn Sie in einer Überschrift eine UI-Referenz hinzufügen müssen, ist die Syntax etwas anders, da Hugo Überschriften anders rendert als den Rest des Textes:

{{% uiref "Search > Designs > New Design > Omnisearch" %}}

Die Ausgabe davon wird als fetter Text angezeigt, der in allen Übersetzungen gleich bleibt: Search > Designs > New Design > Omnisearch

Hinweise #

Dies sind farbige Kästen, die verwendet werden können, um wichtige Punkte hervorzuheben. Sie sollten sparsam verwendet werden und nur, wenn etwas besonders wichtig ist.

Das bedeutet auch, dass jeder einzelne Artikel im Allgemeinen nicht mehr als 1 von jeder dieser Arten enthalten sollte, da sie ansonsten den Artikel überkomplizieren.

Die Syntax ist:

{{< hint info|warning|danger >}}
**Etwas**: Darauf zu achten.
{{< /hint >}}

Es gibt drei Arten von Hinweisen:

Info über etwas, das gut zu wissen ist, wie unser Vorschlag für eine Startvorlage.

Warnung vor etwas, das ein Problem werden könnte, wie das Vergessen zu speichern, bevor man eine Seite verlässt.

Gefahr vor etwas, das eine gesamte Einrichtung brechen könnte, wie das Aktualisieren einer Erweiterung, ohne vorher ein Backup zu erstellen.

Verwenden Sie sie nur, wenn es wirklich notwendig ist, und je nach Schwere dessen, was sie erklären.

Codeblöcke #

Diese kommen in zwei Varianten - inline und block.

Ein inline code block, der mit zwei Backticks `so` erstellt wird.

Vollständige Codeblöcke werden erstellt, indem der Code am Anfang und Ende mit 3 Backticks umschlossen wird und die Programmiersprache für die Syntax hinzugefügt wird:

console.log("Was für ein großartiges Codebeispiel!");

Beginnen Sie zu schreiben #

Jetzt sind Sie bereit, erstklassige Inhalte zu schreiben!

Es gibt viel zu verdauen in diesem Artikel, und Sie werden wahrscheinlich morgen nicht die Hälfte davon erinnern. Machen Sie eine Pause, essen Sie etwas und lesen Sie es erneut.

Suchen Sie dann einen Artikel im Knowledge Center, von dem Sie glauben, dass er besser sein könnte, und schreiben Sie ihn mit diesen Richtlinien um. Halten Sie diesen Leitfaden offen, während Sie schreiben, damit Sie darauf verweisen können.

Wenn Sie Ihr Bestes gegeben haben, suchen Sie nach Feedback von einem Kollegen - es muss nicht länger als 10 Minuten dauern, und sie werden in der Lage sein, Aspekte zu erkennen, die Ihnen möglicherweise nicht aufgefallen sind.

Jeder bekommt Tunnelblick beim Schreiben, daher ist Feedback entscheidend, um die bestmöglichen Inhalte zu schreiben.

Viel Spaß beim Schreiben!

Diese Seite wurde von einer hilfreichen KI übersetzt, daher kann es zu Sprachfehlern kommen. Vielen Dank für Ihr Verständnis.