Wie man großartige Artikel schreibt

Es ist unsere heilige Pflicht (leiser Engelschor), die Navigation einfach zu halten und jeden Artikel hervorragend zu beschreiben, damit das Knowledge Center ein unverzichtbares Werkzeug bleibt, um die Lücke zwischen Product und dem Rest des Unternehmens zu überbrücken.

Jeder Artikel, den du schreibst, wird potenziell hunderte, wenn nicht sogar tausende Male gelesen – also solltest du auf höchste Qualität achten.

Writing Style #

Wie schwer kann es sein, eine Dokumentation zu schreiben? Man tippt ein paar Worte hin, zeigt, wo man klicken muss, und fügt einen Screenshot hinzu, oder?

Jein. Hauptsächlich nein.

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

Denke an die Hauptgründe, warum Apple eines der führenden Elektronikunternehmen der Welt ist. Sie machen doch nur Telefone und Laptops, oder?

Ja, aber sie stellen diese auch in einer extrem klaren und konsistenten Qualität her, die fast religiöse Fangemeinden schafft, die auf ihr Ökosystem schwören.

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

Dieser muss durchgehend großartig sein, damit Kolleg:innen und Kund:innen genauso religiös am Benutzen bleiben, wie wir es uns wünschen ;)

Schauen wir uns an, wie du das erreichen kannst.

Voice & Tone #

Wenn wir für unsere Kund:innen schreiben, legen wir Wert darauf, Dinge klar und verständlich zu machen. Unser Ziel ist es, nützliche Informationen bereitzustellen, ohne zu verwirren. Wir vermeiden komplizierte Sprache und stellen sicher, dass jeder notwendige Schritt erklärt ist.

Wir schreiben für technische und nicht-technische Leser:innen, daher müssen unsere Artikel einfach, aber informativ für beide Zielgruppen sein. Wir erreichen das durch starken Text und eine klare Struktur.

Humor ist willkommen, solange er natürlich passt. Am wichtigsten ist aber, dass wir helfen wollen, ohne herablassend zu sein oder zu unterstellen, dass unsere Leser:innen alles wissen.

1. Einfach halten: Verwende klare, leicht verständliche Sprache. Vermeide lange, verwirrende Sätze und schwierige Wörter. Nutze den Aktiv, um den Text direkt und leicht lesbar zu machen.

2. Respektvoll sein: Schreibe so, dass du die Leser:innen als gleichwertig behandelst. Gehe nicht davon aus, dass sie alles wissen. Gib alle nötigen Details an und, falls nötig, Links zu weiterführenden Informationen.

3. Klar und hilfreich: Gib hilfreiche Informationen statt langer Erklärungen. Leite die Leser:innen Schritt für Schritt an und denke darüber nach, wonach sie suchen könnten, damit sie die Antworten leicht finden.

4. Humor vorsichtig einsetzen: Humor ist großartig, wenn er natürlich passt, aber er sollte niemals gezwungen wirken. Bist du dir nicht sicher, ob er passt, lass ihn weg. Der Fokus bleibt auf Hilfsbereitschaft und Klarheit.

Unser Ton ist informell mit starkem Fokus auf Klarheit. Humor ist erwünscht, aber nur, wenn er zur Denkweise der Nutzer:innen beim Lesen passt. Denke daran, warum sie hier sind. Wer z.B. einen Artikel liest, der erklärt wie Search funktioniert, hat wahrscheinlich eine Entdecker-Mentalität – da kann Humor gut funktionieren.

Wer hingegen FAQs oder Problembehebungsartikel liest, ist meist genervt durch ein Problem und benötigt einfach eine klare Lösung. Denkweise ist alles ;)

Wenn Humor verwendet wird, dann bitte nerdig – wir lieben Anspielungen auf Star Wars, Herr der Ringe, The Matrix und andere Phänomene der Geek-Kultur. Besonders in Code-Beispielen kommt das oft sehr gut an ;)

Types of articles #

Überlege beim Schreiben, welcher dieser Typen das Bedürfnis der User am besten löst.

Informational #

Erklärt die Konzepte eines Produkts oder Features. Leser sind meist im Entdecker-Modus und wollen verstehen, wie etwas funktioniert. Diese Artikel beinhalten keine Handlungsschritte oder ausführliche Backend-Anleitungen, sondern erklären klar, wie die einzelnen Teile funktionieren.

Beispiele:

• Cookieless
• Dashboard
• Conversations

How-Tos #

Erklärt, wie man ein bestimmtes Ziel erreicht. Diese benötigen eine Schritt-für-Schritt-Anleitung, welche genau beschreibt, welche Schaltflächen geklickt und welche Konfigurationen vorgenommen werden sollen. Leser möchten hier meist etwas ganz Bestimmtes erreichen.

Beispiele:

• Get Started on Shopify
• Recommendations Best Practices
• Adding a new Store

FAQs / Troubleshooting #

Erklärt die wahrscheinlichsten Lösungen zu häufigen Fragen oder Problemen. Leser sind dabei oft schon frustriert, weil etwas nicht wie erwartet funktioniert. Die Artikel sollten klar mit der Frage, die Leser:innen haben könnten, überschrieben und die Lösung verständlich erklärt sein.

Dies sind nie einzelne Artikel, sondern werden in der FAQ für das jeweilige Produkt, Feature oder die Integration gesammelt.

Beispiele:

• Any Webshop FAQ
• Lightspeed 429 Error
• Magento 2 403 Forbidden Error

Intros #

Fällt dir auf, wie dieser Artikel und die Writing Style-Abschnitte immer mit einem kleinen Intro beginnen? Was wurde damit erreicht?

Intros erklären, warum etwas wichtig zu lesen ist. Sie fangen die Aufmerksamkeit der Leser:innen ein und helfen schnell festzustellen, ob der Inhalt „sitzt“.

Intros sollten nicht zu lang sein, aber den Lesenden den Kontext geben, was sie erwartet.

Füge immer Intros am Anfang von Artikeln und bei neuen Abschnitten mit einer h2-Überschrift ein.

Title & Description #

Der Titel deines Artikels sollte immer klar und knapp sein. Ein guter Titel hat maximal 3 Wörter, idealerweise nur 1.

Ein guter Titel ist „Omnisearch“. Eine schlechte Version wäre „Unsere Omnisearch-Funktion“. Das sind zu viele unnötige Wörter und machen die Menüstruktur schwerer durchschaubar.

Kurze Titel sind leicht zu überblicken und mit einer logischen Menüstruktur bleibt das Knowledge Center einfach zu navigieren.

Die Beschreibung sollte eine einzige prägnante Phrase sein, die dem Artikel Kontext verleiht. Sie hilft Lesenden festzustellen, ob das der gesuchte Artikel ist. Wiederhole den Titel nicht in der Beschreibung – sie sollte den Titel ergänzen.

Eine gute Beschreibung für Omnisearch ist: „Ein Seitenfüllendes Fenster, das Besucher:innen die Ergebnisse zeigt, die am wahrscheinlichsten konvertieren.“ Das erklärt, was Omnisearch ist, in einem Satz.

Eine schlechte Beschreibung ist: „Omnisearch ist eine neue Funktion unseres Suchprodukts.“ Sie wiederholt den Namen und Platz in unserem Katalog, was im Knowledge Center-Menü ohnehin klar ist.

Headings #

Sie sind essentiell, damit Artikel leicht zu überfliegen und zu navigieren sind. Nutze sie, um die Bereiche klar zu trennen. Überschriften sind maximal drei Wörter lang.

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

• h1: Nur für den Titel
• h2: Hauptabschnitt
• h3: Untertitel von h2
• h4: Untertitel von h3

Wir verwenden nie Überschriften kleiner als h4.

Alle h2 und h3 werden automatisch für das Inhaltsverzeichnis genutzt.

Paragraphs #

Artikel sollen so geschrieben sein, dass Lesende sie leicht überblicken und verstehen können. Meist lesen sie nicht den ganzen Artikel, sondern überfliegen ihn und suchen das Relevante.

Der ideale Absatz ist 1–3 Zeilen lang. Längere Absätze wirken schnell wie Textwände. Achte darauf, dass deine Texte gut überfliegbar sind – füge nach spätestens 3 Zeilen (auf einem 13-Zoll-Laptop betrachtet) Zeilenumbrüche ein.

Das ist keine strenge Regel, sondern eine sinnvolle Faustregel. Unser Gehirn beurteilt große Textblöcke oft als schwer zu lesen, selbst wenn sie es eigentlich nicht sind.

Um den Unterschied zu veranschaulichen, schau dir den Abschnitt unten an, wo keine Zeilenumbrüche gemacht wurden. Schwerer zu überfliegen, oder?

Artikel sollen so geschrieben sein, dass Lesende sie leicht überblicken und verstehen können. Meist lesen sie nicht den ganzen Artikel, sondern überfliegen ihn und suchen das Relevante. Der ideale Absatz ist 1–3 Zeilen lang. Längere Absätze wirken schnell wie Textwände. Achte darauf, dass deine Texte gut überfliegbar sind – füge nach spätestens 3 Zeilen (auf einem 13-Zoll-Laptop betrachtet) Zeilenumbrüche ein. Das ist keine strenge Regel, sondern eine sinnvolle Faustregel. Unser Gehirn beurteilt große Textblöcke oft als schwer zu lesen, selbst wenn sie es eigentlich nicht sind. Um den Unterschied zu veranschaulichen, sieh den Abschnitt oben, in dem Zeilenumbrüche gesetzt wurden. Leichter zu lesen, oder?

Links #

Verlinke sinnvollerweise auf andere Bereiche des Knowledge Centers. Bedenke: User:innen sollten in jedem Artikel alles Notwendige finden, deshalb lohnt es oft, Kernaussagen zusammenzufassen, bevor du für weitere Infos auf einen anderen Artikel verweist.

Beispiel:

Bevor du fortfährst, erstelle ein neues Element. Das machst du unter Recommendations > Elements > Create New. Mehr zu Elements hier.

Screenshots #

Wir nutzen Brandbird für ansprechende Screenshots. Verwende immer einen kontrastreichen Hintergrund, der nicht ablenkt, sondern das Bild unterstützt.

Screenshots zeigen den Lesenden, dass sie sich an der richtigen Stelle im Backend befinden. Ihr Hauptzweck ist Kontext, nicht jede einzelne Interaktion zu zeigen. Der Text erledigt das.

Eine gute Faustregel ist: Maximal so viele Bilder einbauen wie du h2- und h3-Überschriften hast. Weniger ist oft mehr – siehe das Beispiel von Linear, das sparsam Bilder nutzt, aber stark im Text ist.

Ein Screenshot sollte in der Regel alle relevanten Inhalte auf einer Seite zeigen und von erklärendem Text begleitet werden.

Statt z.B. drei verschiedene Bilder für HTML, CSS und Sub-Designs, zeige eine Gesamtansicht im ersten Abschnitt. Anmerkungen/Annotationen helfen, Bildbereiche zu verdeutlichen.

Videos #

Wir nutzen Loom oder Tella zum Aufzeichnen von Videos. Nutze deren jeweilige Embed-Funktionen und wähle immer die Responsive-Version. Videos können so eingebettet werden:

Videos eignen sich für die klare Darstellung aller Aspekte eines Features oder eines Vorgangs. Sie ergänzen Anleitungen gut, da viele erst das Video schauen, danach aber die Artikelreferenz nutzen.

Videos sollten aber nie den geschriebenen Text ersetzen – alles, was im Video gezeigt wird, sollte auch im Text stehen.

Achte beim Aufnehmen darauf, die Punkte in der gleichen Reihenfolge wie im Artikel zu behandeln, damit die Nachvollziehbarkeit stimmt.

Menu Items #

Wir strukturieren das Knowledge Center logisch und in der Regel in derselben Reihenfolge, wie Features im Backend angezeigt werden.

Nur Artikel, die für alle Kund:innen relevant sind, erhalten eigene Seiten. Sonderfälle werden bei den passenden FAQs ergänzt.

Beispiele:

• Ein Artikel, der erklärt, wie Omnisearch funktioniert, ist für alle Nutzer:innen in dem Produkt relevant, deshalb gibt es einen eigenen Artikel.
• Debugging, warum getrackte Bestellungen nicht im Dashboard angezeigt werden, ist ein Sonderfall und kommt in die FAQ für Any (Webshop)

Hugo #

Unser gesamtes Knowledge Center baut auf Hugo Themes auf – ein leichtgewichtiges Template-System, das aus Markdown statische HTML-Dateien generiert. So arbeiten wir ausschließlich im Verzeichnis /content und Hugo rendert alles wunderschön im gewünschten Theme.

Wie du mit Hugo startest, steht in der Datei README.md im Root-Ordner oder im Github-Repo.

Folders & files #

Du arbeitest im Verzeichnis content/en sowie in den Unterordnern integrations & platform.

Übersetzungen laufen über Localazy – siehe das README.md im Root-Ordner.

Der Dateibaum spiegelt die Menüstruktur wider, da Hugo die Navigation auf Basis der Ordnerstruktur wie unten abbildet.

Jeder Artikel liegt in einem eigenen Ordner mit einer _index.md-Datei, die du bearbeitest. Der Unterstrich ist notwendig, damit Hugo erkennt, dass es sich um eine Landingpage handelt.

Standardmäßig bestimmt der Ordnername den Artikeltitel – wähle ihn mit Bedacht und orientiere dich an existierenden Beispielen. Der Titel kann im Frontmatter eines 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 eines Artikels wird durch die Ordnerstruktur bis zur letzten Ebene gebildet, wo die _index.md-Datei liegt. Für das obige Beispiel ist die URL /integrations/act-on/email-recs

Front Matter #

Das ist Meta-Information, die du für Artikel festlegen kannst: Titel, Beschreibung, Aliases (Weiterleitungen), Kategorien usw.

Front Matter steht immer am Anfang eines Artikels:

---
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
---

Wie schnell fliegt eigentlich eine unbeladene Schwalbe?...

Die wichtigsten Front Matter-Felder:

• title: Eigener Titel des Artikels, überschreibt den Menüpunkt. Fehlt das Feld, wird der (Title Cased) Ordnername genutzt.
• onPageTitle: Titel, der nur auf der Artikelseite angezeigt wird, nicht im Menü. Gut für SEO, falls die Webseitentitel z.B. “Wie Produkt-Logiken funktionieren” sein sollen, aber der Menüpunkt einfach “Logics” lautet.
• description: Wird direkt unter dem Titel angezeigt. Pflichtfeld, da es wertvollen Kontext bietet.
• weight: Die Reihenfolge innerhalb des Menüs. Je niedriger, desto weiter oben.
• aliases: Alte URLs, unter denen der Artikel früher lag. Hugo leitet dorthin weiter, um 404-Fehler zu vermeiden. Ändere nie die Ordnernamen; nutze besser den title-Tag.

Markdown #

Eine hervorragende Auszeichnungssprache, mit der du dich ganz auf den Inhalt konzentrieren kannst, statt dich mit HTML und CSS aufzuhalten.

Markdown-Dateien werden in HTML umgewandelt und Kund:innen angezeigt.

Es ist extrem intuitiv. Falls du mal einen Spickzettel brauchst, schau auf der offiziellen Seite vorbei.

Hier die gebräuchlichsten Syntaxregeln:

Headers #

Überschriften werden mit einer passenden Anzahl von # vor dem Text erzeugt.

Die Zahl der Rauten bestimmt die Überschriftenebene:

h2: ## Shortcodes
h3: ### Their syntaxes
h4: #### A specific syntax

Paragraphs #

Alle Textzeilen, die direkt aufeinander folgen, sind ein Absatz. Ein Zeilenumbruch trennt Absätze:

Alles hier ist ein Absatz.
Auch dieser Satz ist im selben Absatz wie oben.

Dieser Text beginnt einen neuen Absatz.

Links & Anchors #

Um Links einzufügen, markiere den gewünschten Text und setze eckige Klammern darum, gefolgt von runden Klammern mit dem Link.

... lies mehr über [Content hier](/platform/elements/settings/)

Verweise auf Knowledge Center-Artikel benötigen nur den relativen Pfad. Für externe Links nutze die vollständige URL.

Mit Anchors führst du Leser:innen zu bestimmten Abschnitten in langen Artikeln – einfach # mit der (bereinigten) Überschrift-ID anhängen.

Die ID wird aus dem Überschriftentext abgeleitet. Für „For Developers“ ist das z.B. for-developers.

Das lässt sich für interne Sprünge verwenden oder beim Verlinken anderer Artikel, indem auch deren relativer Pfad genutzt wird:

Sieh dir den [For Developers](#for-developers) Abschnitt weiter unten an.

Mehr zu [Common sync errors für Magento2 hier](/integrations/magento-2/faq/#common-sync-issues).

Images #

Wir verwenden ein angepasstes Shortcode für Screenshots in Artikeln.

Exportiere Bilder immer als .webp aus Brandbird, um hohe Qualität und geringe Dateigröße zu kombinieren.

Bilder werden im selben Ordner wie die jeweilige _index.md gespeichert, so bleibt alles ordentlich.

Der Shortcode ist:

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

Ergänze immer einen Alt-Text, damit Suchmaschinen das Bild einordnen können.

Automatic Backgrounds #

Bilder bekommen automatisch einen dekorativen Hintergrund. So entsteht ein Schweb-Effekt mit feinem Schatten.

Falls ein Bild bereits einen eigenen Hintergrund (z.B. von Brandbird) hat, kannst du diesen ausschalten – einfach "no-background" als dritten Parameter ergänzen:

{{< image "IMAGE_ALT" "FILENAME.webp" "no-background" >}}

Nutze "no-background", wenn dein Screenshot bereits einen eigenen Rahmen oder Stil hat.

UI references #

Um Menüpunkte korrekt und unabhängig von der Übersetzung zu referenzieren, nutzen wir ein spezielles Shortcode.

Syntax:

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

Falls du einen UI-Referenz in einer Überschrift brauchst, ist der Syntax leicht abweichend, weil Hugo Überschriften anders rendert:

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

Das Ergebnis erscheint als fetter Text und bleibt in allen Sprachen identisch: Search > Designs > New Design > Omnisearch

Callouts #

Das sind farbige Boxen, um wichtige Infos hervorzuheben. Nutze sie sparsam – pro Artikel maximal eine Box pro Typ (sonst wird’s unübersichtlich).

Syntax:

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

Die drei Typen:

Info zu einem nützlichen Hinweis – etwa unsere Start-Template-Empfehlung.

Warnung vor möglichen Problemen – zum Beispiel „Speichern nicht vergessen“.

Gefahr: Etwas, das eine ganze Konfiguration zerstören könnte, z.B. „Vor dem Upgrade ein Backup machen“.

Einschränkung: Nur einsetzen, wenn es wirklich nötig ist und in entsprechender Gewichtung!

Code blocks #

Es gibt zwei Varianten – inline und Block.

Ein Inline-Codeblock entsteht mit zwei Backticks `so hier`.

Komplette Codeblöcke erreichst du mit drei Backticks sowie der Programmiersprache davor:

console.log("What an awesome code example!");

Start writing #

Jetzt bist du bereit, Weltklasse-Inhalte zu schreiben!

Dieser Artikel enthält viele Informationen – wahrscheinlich wirst du morgen die Hälfte vergessen haben. Mach eine Pause, iss etwas und lies ihn nochmal.

Such dir dann einen Artikel im Knowledge Center, den du verbessern könntest, und schreibe ihn nach diesen Grundsätzen um. Lass diese Anleitung offen, um immer wieder reinzuschauen.

Wenn du dein Bestes gegeben hast, hol dir Feedback von einer Kollegin oder einem Kollegen – das muss nicht länger als zehn Minuten dauern, aber sie sehen Aspekte, die dir nicht auffallen würden.

Jeder bekommt beim Schreiben Betriebsblindheit – Feedback ist entscheidend für besten Content.

Viel Spaß beim Schreiben!