Wie man großartige Artikel schreibt

Über die Produkte und Funktionen von Clerk 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 (leiser Engelschor), das Ganze einfach navigierbar zu halten und jeden Artikel hervorragend zu beschreiben, damit es ein unverzichtbares Werkzeug bleibt, um die Lücke zwischen Product und dem Rest des Unternehmens zu schließen.
Jeder Artikel, den du schreibst, könnte hunderte oder sogar tausende Male gelesen werden – du solltest also auf die Qualität achten.
Schreibstil #
Wie schwer kann es sein, Dokumentation zu schreiben? Man schreibt ein paar Worte auf, zeigt, wohin man gehen soll, und fügt einen Screenshot hinzu, oder?
Nun, ja und nein. Eigentlich meistens nein.
Wie wir Dokumentation schreiben, ist ebenso entscheidend wie was wir schreiben. Es ist im Grunde das UX unserer Arbeit.
Denke nur daran, warum Apple einer der führenden Elektronikkonzerne der Welt ist. Sie bauen doch auch „nur“ Telefone und Laptops, oder?
Ja, aber sie bauen sie in einer so hochwertigen und konsistenten Qualität, dass fast schon religiöse Fangruppen ihrem Ökosystem schwören.
Design ist wichtig, und das Design eines Knowledge Center-Artikels ist der Schreibstil.
Dieser muss konsequent großartig sein, damit Kollegen und Kunden genauso religiös von der Nutzung überzeugt sind, wie wir es uns wünschen ;)
Schauen wir uns an, wie du das erreichen kannst.
Voice & Tone #
Beim Schreiben für unsere Kunden legen wir Wert darauf, Dinge klar und 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 ist.
Wir schreiben sowohl für technische als auch für nicht-technische Leser, daher müssen unsere Artikel für beide Zielgruppen einfach, aber informativ sein. Das erreichen wir durch gelungenes Copywriting und eine klare Struktur.
Humor ist willkommen, aber nur, wenn er natürlich passt. Am wichtigsten ist, unseren Kunden zu helfen, ohne sie zu belehren oder zu glauben, sie wüssten bereits alles.
Halte es einfach: Nutze klare, leicht verständliche Sprache. Vermeide lange, verwirrende Sätze und komplizierte Wörter. Verwende Aktiv statt Passiv für direkte und gut lesbare Texte.
Respektvoll bleiben: Schreibe so, dass der Leser als gleichwertig behandelt wird. Gehe nicht davon aus, dass Vorwissen vorhanden ist. Gib alle nötigen Details mit und verlinke ggf. zu mehr Infos.
Klar und hilfreich: Gib hilfreiche Informationen statt langer Erklärungen. Führe den Leser Schritt für Schritt, und überlege, wonach er suchen könnte, sodass er Antworten leicht findet.
Humor vorsichtig einsetzen: Humor ist super, wenn er natürlich passt, sollte aber nie erzwungen sein. Wenn du dir unsicher bist, lass ihn weg. Der Fokus liegt auf Hilfsbereitschaft und Klarheit.
Unser Ton ist informell mit starkem Fokus auf Klarheit. Humor ist erwünscht, aber nur, wenn er zur Denkweise eines Nutzers passt, der den Artikel liest. Überlege dir, warum Nutzer hier sind. Liest jemand einen Artikel, der erklärt, wie Search funktioniert, ist er wahrscheinlich neugierig und Humor kann gut passen.
Liest er FAQs oder Anleitungen zur Fehlerbehebung, ist der Nutzer vermutlich schon frustriert aufgrund eines Problems – da zählt eine klare Lösung. Die Denkweise zählt ;)
Wenn Humor verwendet wird, mach ihn nerdig – wir lieben Anspielungen auf Star Wars, Herr der Ringe, Matrix und andere Geek-Kultur-Phänomene. Das passt oft super in Code-Beispielen, wie du sehen wirst ;)
Artikeltypen #
Überlege dir beim Schreiben, welche dieser Typen das Anliegen des Nutzers am besten löst.
Informational #
Erklärt die Konzepte eines Produkts oder einer Funktion. Leser sind meist im Entdeckungsmodus und wollen verstehen, wie etwas funktioniert. Diese Artikel enthalten keine Schritt-für-Schritt-Anleitungen oder detaillierte Backend-Anweisungen, sondern erklären klar, wie die einzelnen Teile funktionieren.
Beispiele:
How-Tos #
Erklären, wie ein bestimmtes Ziel erreicht wird. Hier sind Schritt-für-Schritt-Anleitungen gefragt, die genau erklären, welche Buttons zu klicken sind und welche Einstellungen notwendig sind. Leser möchten gezielt etwas umsetzen.
Beispiele:
FAQs / Troubleshooting #
Erklären die wahrscheinlichsten Lösungen für häufige Fragen oder Probleme. Leser sind beim Stöbern oft schon genervt, weil etwas nicht wie erwartet funktioniert. Diese Artikel sollten deutlich mit der Frage, die der Leser hat, gekennzeichnet sein und eine klare Problemlösung bieten.
Das sind nie Einzelartikel, sondern werden unter FAQ für das jeweilige Produkt, Feature oder die Integration gesammelt.
Beispiele:
Intros #
Merkst du, wie dieser Artikel und die Abschnitte zum Schreibstil mit einem kleinen Intro beginnen? Hast du bemerkt, was sie erreicht haben?
Intros erklären, warum etwas wichtig ist zu lesen. Sie sollen die Aufmerksamkeit des Lesers gewinnen und ihm signalisieren, ob er mit dem Inhalt richtig ist.
Intros sollten nicht zu lang sein, aber sie sollen den Lesern den Kontext geben, worum es gleich gehen wird.
Beginne immer mit einem Intro zu Beginn eines Artikels und bei jedem neuen Abschnitt mit h2-Überschrift.
Titel & Beschreibung #
Der Titel des Artikels sollte immer klar und knapp sein. Ein guter Titel besteht maximal aus 3 Wörtern, idealerweise nur aus 1.
Ein guter Titel ist “Omnisearch”. Eine schlechte Variante wäre “Our Omnisearch Feature”. Zu viele unnötige Worte erschweren die Navigation im Menü.
Kurze Titel funktionieren, weil sie sich leicht überfliegen lassen. Zusammen mit einer logischen Menüstruktur bleibt das Knowledge Center einfach zu navigieren.
Artikelbeschreibungen sind ein einzelner Satz, der dem Artikel Kontext gibt. Leser können so prüfen, ob dies der Artikel ist, den sie gesucht haben. Vermeide, den Titel in der Beschreibung zu wiederholen – sie sollte ihn ergänzen.
Eine gute Beschreibung für Omnisearch ist: „Ein einzelnes Vollbild-Fenster, das Besuchern die Ergebnisse anzeigt, die am wahrscheinlichsten konvertieren.“ Das erklärt, was Omnisearch ist – in einem Satz.
Eine schlechte Beschreibung wäre: „Omnisearch ist ein neues Feature in unserem Search Product.“ Sie wiederholt den Feature-Namen und dessen Platz im Katalog, was schon im Menü des Knowledge Centers klar ist.
Überschriften #
Sie sind entscheidend, damit Artikel leicht überflogen und durchsucht werden können. Nutze sie, um verschiedene Abschnitte klar zu trennen. Überschriften bestehen aus maximal 3 Wörtern.
Überschriften sind hierarchisch und werden stets in folgender Reihenfolge genutzt:
- h1: Nur für den Titel
- h2: Hauptabschnitt
- h3: Untertitel zu h2
- h4: Untertitel zu h3
Kleinere Überschriften als h4 nutzen wir nie.
Alle h2- und h3-Überschriften werden automatisch für das Inhaltsverzeichnis verwendet.
Absätze #
Wir wollen beim Schreiben die Artikel so gestalten, dass Leser sie leicht durchsuchen und verstehen können. Sie lesen selten alles, sondern überfliegen die Inhalte, um den passenden Teil zu finden.
Der ideale Absatz besteht aus 1-3 Zeilen. Längere Absätze werden schnell zu Textwänden. Achte beim Schreiben darauf, spätestens nach der dritten Zeile (bei Ansicht auf einem 13-Zoll-Laptop) einen Zeilenumbruch zu machen, damit der Text gut überfliegbar ist.
Das ist keine strikte Vorgabe, aber eine gute Faustregel. Unser Gehirn beurteilt große Textblöcke oft schon als schwer lesbar, auch wenn das nicht so ist.
Um den Unterschied zu sehen, schau dir den folgenden Abschnitt ohne Zeilenumbrüche an. Schwerer zu scannen, oder?
Wir wollen beim Schreiben die Artikel so gestalten, dass Leser sie leicht durchsuchen und verstehen können. Sie lesen selten alles, sondern überfliegen die Inhalte, um den passenden Teil zu finden. Der ideale Absatz besteht aus 1-3 Zeilen. Längere Absätze werden schnell zu Textwänden. Achte beim Schreiben darauf, spätestens nach der dritten Zeile (bei Ansicht auf einem 13-Zoll-Laptop) einen Zeilenumbruch zu machen, damit der Text gut überfliegbar ist. Das ist keine strikte Vorgabe, aber eine gute Faustregel. Unser Gehirn beurteilt große Textblöcke oft schon als schwer lesbar, auch wenn das nicht so ist. Um den Unterschied zu sehen, schau dir den obigen Abschnitt mit Zeilenumbrüchen an. Leichter zu lesen, oder?
Links #
Füge immer dann Links zu anderen Wissenbank-Artikeln ein, wenn es Sinn ergibt. Der Nutzer soll aber in jedem Artikel alles Wichtige finden können. Es lohnt sich daher meist, die Punkte zumindest zusammenzufassen, bevor zu einem anderen Artikel mit mehr Infos verlinkt wird.
Beispiel:
Bevor du weitermachst, erstelle ein neues Element. Das kannst du unter Recommendations > Elements > Create New machen. Mehr zu Elements findest du hier.
Screenshots #
Wir nutzen Brandbird für schicke Screenshots. Immer einen guten Kontrast als Hintergrund verwenden, der nicht ablenkt, sondern das Bild ergänzt.
Screenshots sind wichtig, weil sie dem Leser zeigen, dass er sich im richtigen Bereich im Backend befindet. Ihr Hauptzweck ist also Kontext, nicht jeden einzelnen Schritt zu zeigen. Das übernimmt das Copywriting.
In der Regel verwenden wir maximal einen kontextbezogenen Screenshot oder ein Video am Anfang eines Artikels. Einige Artikel benötigen gar kein Bild. Bilder im Fließtext nur, wenn etwas gezeigt werden soll, das der Text nicht einfach erklären kann, wie bei einem DNS-Einrichtungsdiagramm.
Schau dir an, wie Linear sparsam mit Screenshots umgeht und gutes Copywriting zur Ergänzung nutzt.
Ein Screenshot sollte genug von der Seite zeigen, um den Leser zu orientieren. Folge auf das Bild mit Text, der die nötigen Schritte oder Funktionen erklärt.
Statt drei einzelner Bilder zu HTML, CSS und Sub-Designs, zeige zum Beispiel ein nützliches Gesamtbild nahe am Anfang des Artikels. Annotationen können wichtige Punkte hervorheben.
Videos #
Wir verwenden Loom oder Tella für Videoaufnahmen. Nutze deren Embed-Funktion und achte darauf, immer die Responsive-Variante zu wählen. Sie können direkt in einen Artikel eingefügt werden, so:
Videos eignen sich hervorragend, um alle Aspekte einer Funktion oder einen bestimmten Ablauf zu zeigen. Sie ergänzen Anleitungen, da Leser meist zunächst das Video ansehen und anschließend den Artikel als Referenz nutzen.
Wenn ein Video das Hauptbild eines Artikels ist, platziere es am Anfang und füge keinen extra Screenshot oben hinzu.
Videos ersetzen nie den Fließtext, daher sollte alles, was im Video gezeigt wird, auch schriftlich erklärt werden.
Beim Aufzeichnen von Videos gehe chronologisch durch die einzelnen Punkte – in derselben Reihenfolge wie im Artikel – damit sie einfach nachvollziehbar sind.
Menüeinträge #
Das Knowledge Center ist logisch aufgebaut – im Allgemeinen in der gleichen Reihenfolge, in der Funktionen im Backend erscheinen.
Nur Artikel, die für alle Kunden relevant sind, bekommen eigene Seiten. Sonderfälle landen als FAQ unter dem jeweiligen Menüpunkt.
Beispiele:
- Ein Artikel zur Erklärung von Omnisearch betrifft alle Nutzer und hat daher einen eigenen Artikel.
- Die Fehlersuche, warum getrackte Bestellungen nicht im Dashboard angezeigt werden, ist ein Sonderfall und findet sich im FAQ für Any (Webshop)
Hugo #
Unser gesamtes Knowledge Center basiert auf Hugo Themes – ein schlankes Templating-System, das statische HTML-Dateien aus Markdown generiert. So arbeitet man vollständig im /content-Ordner und Hugo übernimmt das Rendering über unser Theme.
Wie man mit Hugo startet, steht in der Datei README.md im Root-Ordner oder im
Github-Repo.
Ordner & Dateien #
Gearbeitet wird im content/en-Ordner und den Unterordnern integrations & platform.
Übersetzungen werden von Localazy übernommen, wie in der README.md im Root-Ordner beschrieben.
Der Dateibaum spiegelt die Menüstruktur wider, denn Hugo baut das Menü anhand dieser Ordnerstruktur.
Jeder Artikel liegt in einem eigenen Ordner mit einer _index.md, die du bearbeitest. Der Unterstrich ist nötig, damit Hugo erkennt, dass dies eine Landingpage ist.
Standardmäßig wird der Titel eines Artikels durch den Ordnernamen bestimmt – wähle ihn also mit Bedacht und orientiere dich an den bestehenden Beispielen. Der Titel kann im Front Matter des Artikels überschrieben werden.
root/
├── archetypes/
├── assets/
├── content/
│ └── en
│ └── integrations
│ └── act-on
│ └── email-recs
│ ├── _index.md
│ ├── screenshot_10535...
│ └── platform
│ └── search (the search page file)
│ └── writing (this article)
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml <-- site configuration
Die URL jedes Artikels wird anhand der Ordnerstruktur bis zur letzten Ebene generiert, in der sich die _index.md befindet. Die URL im Beispiel oben ist /integrations/act-on/email-recs
Front Matter #
Das sind Metadaten wie Titel, Beschreibungen, Aliases (Weiterleitungen), Kategorien und mehr.
Front Matter steht immer ganz oben im Artikel:
---
title: "Holy Grail"
onPageTitle: "How to find the Holy Grail"
description: "Monty Pythons bester Film überhaupt"
weight: 3
aliases:
- /old/path/to/holy-grail
- /really/old/path/to/holy-grail
---
Was ist die Fluggeschwindigkeit einer unbeladenen Schwalbe?...
Das wichtigste Front Matter ist:
- title: Ein individueller Titel für den Artikel, im Menü sichtbar. Falls nicht angegeben, wird der kapitalisierte Ordnername verwendet.
- onPageTitle: Ein Titel nur auf der Artikelseite, nicht im Menü. Gut für SEO – z.B. “How Product Logics Work” statt “Logics” im Menü.
- description: Wird direkt unter dem Titel auf der Artikelseite angezeigt – notwendig, um den Lesern Kontext zu geben.
- weight: Die Position des Artikels im Menü. Je niedriger die Zahl, desto weiter oben steht er.
- aliases: Alte URLs, unter denen dieser Artikel erreichbar war. Hugo nutzt dies für Weiterleitungen, um 404-Fehler zu vermeiden. Wenn du einen Artikelfolder umbenennst, musst du die alte URL als Alias hinzufügen. Aber generell gilt: Foldernamen nicht ändern – nutze title statt dessen.
Markdown #
Markdown ist eine großartige Auszeichnungssprache, mit der du dich voll aufs Inhaltliche konzentrieren kannst, statt auch noch mit HTML und CSS kämpfen zu müssen.
Markdown-Dateien werden in HTML übersetzt und dann dem Kunden angezeigt.
Die Nutzung ist sehr intuitiv. Wenn du eine Übersicht brauchst, schau auf der offiziellen Seite nach.
Hier die wichtigsten Syntaxregeln.
Headers #
Mit einer bestimmten Anzahl # gefolgt vom Text wird eine Überschrift erzeugt.
Die Anzahl der Hashes bestimmt die Ebene:
h2: ## Shortcodes
h3: ### Their syntaxes
h4: #### A specific syntax
Paragraphs #
Jeder Text in derselben oder nächsten Zeile wird als ein Absatz dargestellt. Ein Abstand von einer Leerzeile erzeugt einen neuen Absatz:
Alle Texte hier sind ein Absatz.
Auch dieser Text steht in derselben Zeile wie der oben.
Text hier erscheint in einem neuen Absatz.
Links & Anchors #
Erstellst du, indem du den gewählten Text markierst, ihn in eckige Klammern setzt und in Klammern den Link anfügst:
... mehr über [Content hier](/platform/elements/settings/) lesen
Beim Verweis auf Artikel im Knowledge Center reicht der relative Pfad, wie im Beispiel. Für externe Links die komplette URL angeben.
Du kannst Anker mit # gefolgt von der Header-ID für Verweise auf bestimmte Abschnitte nutzen.
Die ID wird aus dem Namen erstellt. Aus “For Developers” wird z.B. for-developers.
Das kann innerhalb eines Artikels für Überschriften oder bei Verweisen auf andere Artikel (inklusive deren Pfad) genutzt werden:
Siehe den Abschnitt [For Developers](#for-developers) weiter unten.
Oder: [Common sync errors for Magento2 hier](/integrations/magento-2/faq/#common-sync-issues).
Images #
Wir nutzen ein angepasstes Shortcode für Screenshots.
Speichere Bilder immer als .webp aus
Brandbird, um eine hohe Qualität und geringe Dateigröße zu erhalten.
Speichere Bilder im selben Ordner wie deine _index.md, um die Organisation zu erhalten.
Shortcode-Syntax:
{{< image "IMAGE_ALT" "FILENAME.webp" >}}
Schreibe immer einen Alt-Text, damit Suchmaschinen das Gezeigte interpretieren können.
Automatische Hintergründe #
Bilder erhalten automatisch einen dekorativen Hintergrund – das erzeugt einen „schwebenden“ Effekt mit Schatten und macht Screenshots ansprechender.
Hat ein Bild schon einen eingebauten Hintergrund (z.B. von Brandbird), kannst du den automatischen Hintergrund mit "no-background" als drittem Parameter deaktivieren:
{{< image "IMAGE_ALT" "FILENAME.webp" "no-background" >}}
Nutze "no-background", wenn der Screenshot bereits einen eigenen Hintergrund oder Rahmen enthält.
UI references #
Das Knowledge Center wird automatisch übersetzt. Um zu vermeiden, dass Menüeinträge übersetzt werden, nutzen wir einen speziellen Shortcode für UI-Verweise.
Syntax:
{{< uiref "Search > Designs > New Design > Omnisearch" >}}
Für UI-Verweise in Headers ist die Syntax etwas anders, da Hugo Überschriften anders rendert:
{{% uiref "Search > Designs > New Design > Omnisearch" %}}
Das Ergebnis wird als fettgedruckter Text angezeigt, der in allen Übersetzungen gleich bleibt: Search > Designs > New Design > Omnisearch
Callouts #
Farbige Boxen, um wichtige Punkte hervorzuheben. Sparsam verwenden – ein Artikel sollte in der Regel nicht mehr als ein Feld je Typ enthalten.
Syntax:
{{< hint info|warning|danger >}}
**Etwas**: Was zu beachten ist.
{{< /hint >}}
Es gibt drei Typen:
Info zu etwas, das gut zu wissen ist, z.B. als Start-Template.
Warnung vor etwas, das zu Problemen führen könnte, z.B. nicht zu speichern vor Verlassen einer Seite.
Gefahr vor etwas, das ein ganzes Setup zerstören könnte, z.B. ein Extension-Upgrade ohne vorheriges Backup.
Nutze sie nur, wenn es wirklich nötig ist und entsprechend der Tragweite.
Codeblocks #
Gibt es als Inline- und Blockvariante.
Ein inline code block entsteht mit zwei Backticks: `so wie dieser`.
Code-Blöcke mit Syntax sind umschlossen von drei Backticks zu Beginn und Ende und dem Namen der Sprache:
console.log("Was für ein großartiges Codebeispiel!");
Leg los! #
Jetzt bist du bereit, Weltklasse-Inhalte zu schreiben!
Es gibt viel zu verarbeiten in diesem Artikel, und du erinnerst dich vermutlich morgen nur an die Hälfte. Mach eine Pause, iss etwas und lies nochmal nach.
Such dann einen Artikel im Knowledge Center, den du für verbesserungswürdig hältst, und schreibe ihn anhand dieser Richtlinien neu. Lass diesen Guide offen, während du schreibst, damit du nachschlagen kannst.
Wenn du dein Bestes gegeben hast, hol dir Feedback von einem Kollegen – das dauert oft keine zehn Minuten und hilft, Aspekte zu erkennen, die dir entgangen sind.
Jeder bekommt eine Art Tunnelblick beim Schreiben, daher ist Feedback entscheidend für den besten Inhalt.
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.