Wie man großartige Artikel schreibt

Es ist unsere heilige Pflicht (leiser Engelschor), es leicht 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 überbrücken.

Jeder Artikel, den du schreibst, wird hunderte, wenn nicht tausende Male gelesen, also solltest du auf die Qualität fixiert sein.

Schreibstil #

Wie schwer kann es sein, Dokumentation zu schreiben? Man tippt ein paar Worte nieder, die zeigen, wohin man gehen soll, und fügt einen Screenshot hinzu, oder?

Nun, ja und nein. Eigentlich meistens nein.

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

Denke an den Hauptgrund, warum Apple eines der führenden Elektronikunternehmen der Welt ist. Sie machen doch einfach nur Telefone und Laptops, oder?

Ja, aber sie stellen diese auch in einer super klaren und konsistenten Qualität her, die fast religiöse Gruppen von Anhängern für ihr Ökosystem schafft.

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

Dieser muss durchweg großartig sein, damit Kolleg:innen und Kund:innen ebenso religiös in der Nutzung investieren, wie wir es uns wünschen ;)

Lass uns darauf eingehen, wie du das erreichen kannst.

Stimme & Ton #

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

Wir schreiben für technische und nicht-technische Leser:innen, daher müssen unsere Artikel für beide verständlich, aber informativ sein. Das erreichen wir durch einen guten Schreibstil und eine klare Struktur.

Humor ist willkommen, aber nur, wenn er natürlich passt. Am wichtigsten ist, unseren Nutzer:innen zu helfen, ohne sie zu bevormunden oder davon auszugehen, dass sie alles wissen.

1. Keep It Simple: Verwende klare, verständliche Sprache. Vermeide lange, verwirrende Sätze und komplizierte Wörter. Nutze Aktiv statt Passiv, um den Text direkt und leicht lesbar zu machen.

2. Be Respectful: Schreibe so, dass du die Leser:innen als Gleichberechtigte behandelst. Gehe nicht davon aus, dass sie schon alles wissen. Gib alle nötigen Informationen mit Links zu weiteren Infos, wenn nötig.

3. Be Clear and Helpful: Konzentriere dich darauf, nützliche Informationen anstatt langer Erklärungen zu geben. Führe Schritt für Schritt durch den Prozess und überlege, nach welchen Begriffen Nutzer:innen suchen, um die Antwort leicht zu finden.

4. Use Humor Carefully: Humor ist toll, wenn er natürlich passt, sollte aber niemals erzwungen werden. Wenn du dir nicht sicher bist, lass ihn lieber weg. Der Fokus liegt immer auf Hilfestellung und Klarheit.

Unser Ton ist informell mit starkem Fokus auf Klarheit. Humor ist willkommen, aber nur, wenn er zur Situation passt. Überlege, warum Nutzer:innen gerade hier sind. Wenn ein:e Nutzer:in liest, wie Search funktioniert, ist sie wahrscheinlich in Entdeckerlaune – dort funktioniert Humor gut.

Wenn sie hingegen FAQs oder Artikel zur Fehlerbehebung lesen, sind sie vermutlich frustriert und brauchen einfach eine klare Lösung. Denk an die Stimmung ;)

Wenn Humor verwendet wird, sei nerdig – wir lieben Anspielungen auf Star Wars, Lord of the Rings, The Matrix oder andere Geek-Kultur-Phänomene. Das funktioniert besonders gut in Code-Beispielen, wie du noch sehen wirst ;)

Artikeltypen #

Überlege beim Schreiben, welcher dieser Typen den Nutzerbedarf am besten erfüllt.

Informationell #

Erklärt die Konzepte eines Produkts oder Features. Leser:innen sind meist im Entdeckermodus und möchten verstehen, wie etwas funktioniert. Diese Artikel enthalten keine ausführlichen Schritt-für-Schritt-Anleitungen, sondern erklären klar, wie jeder Teil funktioniert.

Beispiele:

• Cookieless
• Dashboard
• Conversations

How-Tos #

Erklärt, wie ein bestimmtes Ziel erreicht wird. Diese Artikel verlangen Schritt-für-Schritt-Anleitungen, die genau beschreiben, auf welche Buttons die Nutzer:innen klicken und welche Konfigurationen sie durchlaufen sollen. Leser:innen 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 für häufige Fragen oder Probleme. Leser:innen sind oft frustriert, weil etwas nicht wie erwartet funktioniert. Diese Artikel sollten klar mit der Frage beschriftet sein, die der Lesende im Kopf hat und erklären eindeutig, wie das Problem gelöst wird.

Das sind nie Einzelartikel, sondern werden unter FAQ für das jeweilige Produkt, Feature oder Integration gesammelt.

Beispiele:

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

Einleitungen #

Fällt dir auf, dass dieser Artikel und die Abschnitte zum Schreibstil mit einer kleinen Einleitung beginnen? Hast du gemerkt, was sie bewirken?

Einleitungen erklären, warum etwas wichtig ist. Sie sollen die Aufmerksamkeit der Leser:innen gewinnen und helfen, schnell zu erkennen, ob sie den richtigen Inhalt gefunden haben.

Einleitungen sollten nicht zu lang sein, aber dem Leser den Kontext liefern, worum es im Folgenden geht.

Immer Einleitungen am Anfang von Artikeln und bei neuen Abschnitten mit einer h2-Überschrift verwenden.

Titel & Beschreibung #

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

Ein guter Titel wäre “Omnisearch”. Eine schlechte Version ist “Our Omnisearch Feature”. Das sind zu viele unnötige Wörter und erschwert die Navigation im Menü.

Kurze Titel funktionieren gut, weil sie leicht zu überfliegen sind. In Kombination mit einer logischen Menüstruktur bleibt das Knowledge Center einfach zu navigieren.

Artikelbeschreibungen sollten aus einem einzigen Satz bestehen, der zusätzlichen Kontext liefert. Sie helfen dem Leser zu erkennen, ob er den richtigen Artikel gefunden hat. Vermeide es, den Titel in der Beschreibung zu wiederholen – sie sollte ihn ergänzen.

Eine gute Beschreibung für Omnisearch ist: “A single full-page window that serves your visitors with the results that are most likely to convert”. Sie erläutert in einem Satz klar, was Omnisearch ist.

Eine schlechte wäre: “Omnisearch is a new feature in our search product”. Sie wiederholt den Namen und seine Zuordnung, was aus dem Menü bereits klar ist.

Überschriften #

Sie sind entscheidend, damit Artikel leicht überflogen und navigiert werden können. Nutze sie, um verschiedene Abschnitte klar zu trennen. Überschriften sind maximal 3 Wörter lang.

Überschriften sind hierarchisch und werden immer so genutzt:

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

Wir nutzen keine Überschriften kleiner als h4.

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

Absätze #

Wir wollen, dass Leser:innen die Artikel leicht durchgehen und verstehen können. In der Regel liest niemand den gesamten Text, sondern überfliegt ihn, um den relevanten Abschnitt zu finden.

Der ideale Absatz hat 1-3 Zeilen. Längere Absätze enden schnell als Textwände. Sorge beim Schreiben dafür, dass man den Artikel leicht überfliegen kann, indem du nach spätestens jeder dritten Zeile (auf einem 13-Zoll-Laptop betrachtet) einen Zeilenumbruch einfügst.

Das ist zwar keine strenge Vorschrift, aber eine gute Faustregel. Unser Gehirn nimmt große Textblöcke oft als schwer lesbar wahr, selbst wenn sie es nicht wirklich sind.

Um den Unterschied zu sehen, schau dir den folgenden Abschnitt an, bei dem die Zeilenumbrüche entfernt wurden. Schwerer zu überfliegen, oder?

Wir wollen, dass Leser:innen die Artikel leicht durchgehen und verstehen können. In der Regel liest niemand den gesamten Text, sondern überfliegt ihn, um den relevanten Abschnitt zu finden. Der ideale Absatz hat 1-3 Zeilen. Längere Absätze enden schnell als Textwände. Sorge beim Schreiben dafür, dass man den Artikel leicht überfliegen kann, indem du nach spätestens jeder dritten Zeile (auf einem 13-Zoll-Laptop betrachtet) einen Zeilenumbruch einfügst. Das ist zwar keine strenge Vorschrift, aber eine gute Faustregel. Unser Gehirn nimmt große Textblöcke oft als schwer lesbar wahr, selbst wenn sie es nicht wirklich sind. Um den Unterschied zu sehen, schau dir den oberen Abschnitt an, bei dem die Zeilenumbrüche enthalten sind. Leichter zu lesen, oder?

Links #

Wann immer es sinnvoll ist, verlinke auf andere Teile des Knowledge Center. Denke daran, dass Nutzer:innen alles Wichtige in einem einzelnen Artikel finden sollten, fasse also wichtige Punkte zumindest kurz zusammen, bevor du zu einem anderen Artikel mit mehr Informationen verlinkst.

Beispiel:

Before you continue, make sure to create a new Element. You can do this from Recommendations > Elements > Create New. Read more about Elements here.

Screenshots #

Wir verwenden Brandbird, um Screenshots im passenden Look zu erstellen. Immer einen guten Kontrast-Hintergrund nutzen, der nicht ablenkt, sondern das Bild ergänzt.

Screenshots sind wichtig, weil sie zeigen, dass der/die Leser:in an der richtigen Stelle im Backend ist. Ihr Hauptzweck ist also Kontext zu liefern, nicht jede Interaktion zu zeigen. Das übernimmt der Text.

Eine gute Faustregel: Maximal so viele Bilder wie h2- und h3-Überschriften verwenden. Weniger ist auch ok – oft ist weniger mehr bei Screenshots.

Sieh dir an, wie Linear sparsam mit Screenshots umgeht und sie durch guten Text ergänzt.

Ein Screenshot sollte in der Regel die komplette Seite abbilden, gefolgt von erklärendem Text zu den nötigen Schritten oder verfügbaren Funktionen.

Beispiel: Statt drei verschiedene Bilder für HTML, CSS und Sub-Designs, lieber ein Bild, das alles im Einleitungsabschnitt zeigt. Anmerkungen helfen, Teile des Bildes zu erklären.

Videos #

Wir nutzen Loom oder Tella zum Aufzeichnen von Videos. Nutze immer deren Embed-Funktion und wähle die Responsive Version. Videos können so direkt eingefügt werden:

Videos sind ideal, um alle Aspekte einer Funktion oder eines Vorgangs anschaulich zu erklären. Sie ergänzen Anleitungen gut, da Leser:innen oft das Video zuerst ansehen und den Text dann gezielt nachschlagen.

Videos sollten Text nie ersetzen – alles im Video muss auch schriftlich ausgeführt werden.

Führe im Video Schritt für Schritt in derselben Reihenfolge durch wie im Artikel, damit es leicht nachvollziehbar bleibt.

Menüeinträge #

Wir organisieren das Knowledge Center logisch und in der Regel analog zur Reihenfolge im Backend.

Nur Artikel, die für alle Kund:innen relevant sind, erhalten eigene Seiten. Sonderfälle gehören unter die FAQs für den jeweiligen Bereich.

Beispiele:

• Artikel, die erklären, wie Omnisearch funktioniert, sind für alle Nutzer:innen des Produkts relevant und haben daher einen eigenen Artikel.
• Fehlerbehebung dafür, warum getrackte Bestellungen nicht im Dashboard angezeigt werden, ist ein Sonderfall und kommt in die FAQ für Any (Webshop).

Hugo #

Das gesamte Knowledge Center basiert auf Hugo Themes – einem leichtgewichtigen Templating-System, das HTML-Dateien aus Markdown generiert. So arbeiten wir komplett im /content-Ordner und Hugo stellt über unser Theme alles optisch bereit.

Eine Einstiegshilfe zu Hugo findest du in der README.md im Root-Ordner oder im Github-Repo.

Ordner & Dateien #

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

Übersetzungen erfolgen mit Localazy, wie du in der README.md im Root siehst.

Die Dateistruktur spiegelt das Menü wider, da Hugo das Menü auf dem Ordneraufbau basiert.

Jeder Artikel ist in seinem eigenen Ordner mit einer _index.md-Datei, die du bearbeitest. Der Unterstrich ist nötig, damit Hugo erkennt, dass dies eine Einstiegseite ist.

Standardmäßig wird der Titel eines Artikels durch den Ordnernamen bestimmt – wähle diesen also sorgfältig und orientiere dich an den bisherigen Beispielen. Der Titel kann durch die Front Matter im Artikel überschrieben werden.

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

Die URL eines Artikels wird durch die Ordnerstruktur gebildet. Die _index.md-Datei im letzten Ordner definiert die URL, z. B.: /integrations/act-on/email-recs

Front Matter #

Hier legst du Metadaten wie Titel, Beschreibung, Aliase (Redirects), Kategorien und mehr fest.

Front Matter steht immer am Anfang des Artikels:

---
title: "Holy Grail"
onPageTitle: "How to find the Holy Grail"
description: "Monty Python's best movie by far"
weight: 3
aliases:
   - /old/path/to/holy-grail
   - /really/old/path/to/holy-grail
---

What is the airspeed velocity of an unladen swallow?...

Die wichtigsten Front Matter Felder:

• title: Ein individueller Titel – wird im Menü genutzt. Ohne dieses Feld wird der Titel aus dem Ordnernamen genommen.
• onPageTitle: Titel, der nur auf der Artikelseite angezeigt wird, nicht im Menü. Gut für SEO, z. B. “How Product Logics Work” als Seitentitel, Menüpunkt weiterhin “Logics”.
• description: Direkt unter dem Titel auf der Seite angezeigt. Immer erforderlich, da sie wichtigen Kontext bietet.
• weight: Position im Menü – je niedriger, desto weiter oben steht der Artikel.
• aliases: Alte URLs, unter denen der Artikel bereits lief. Hugo leitet diese automatisch weiter und verhindert so 404-Fehler. Wenn der Ordnername einer Seite geändert wird, muss die alte URL hier als Alias stehen. Generell gilt: keine Ordnernamen ändern. Nutze stattdessen title.

Markdown #

Eine tolle Markupsprache, mit der du dich komplett auf den Inhalt konzentrieren kannst – ohne HTML und CSS.

Markdown wird in HTML übersetzt und dem Kunden angezeigt.

Die Nutzung ist super intuitiv. Eine Vorlage findest du auf der offiziellen Seite.

Im Folgenden die wichtigsten Syntax-Regeln.

Überschriften #

Fügst du durch eine Anzahl # vor dem Überschriftentext hinzu.

Die Anzahl bestimmt die Überschrift:

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

Absätze #

Jeder Text in derselben oder der nächsten Zeile wird als ein Absatz angezeigt. Eine Leerzeile zwischen Texttrennungen markiert neue Absätze:

All text here is one paragraph.
Even the text here will be on the same line as the one above.

Text displayed here gets its own paragraph.

Links & Anker #

Links können gesetzt werden, indem du den gewünschten Text markierst, in eckige Klammern schreibst und die URL in runde Klammern anhängst

... read more about [Content here](/platform/elements/settings/)

Beim Verweis auf Artikel im Knowledge Center genügt der relative Pfad wie im Beispiel. Für externe Links immer die komplette URL angeben.

Mit Ankern (Anchors) kann man zu bestimmten Abschnitten springen – dazu ein # plus die ID der Überschrift.

Die ID wird aus dem Namen gebildet, z. B. bekommt “For Developers” die ID for-developers.

Dies funktioniert innerhalb desselben Artikels oder beim Verweis auf andere Artikel:

Check the [For Developers](#for-developers) section further down.

Check [Common sync errors for Magento2 here](/integrations/magento-2/faq/#common-sync-issues).

Bilder #

Wir verwenden einen eigenen Shortcode für Screenshots in Artikeln.

Speichere Bilder immer als .webp über Brandbird, um Qualität und Dateigröße zu optimieren.

Lege Screenshots immer in dem Ordner ab, in dem auch deine _index.md liegt.

Shortcode-Syntax:

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

Immer einen Alt-Text ausfüllen, damit Suchmaschinen das Bild erfassen können.

Automatische Hintergründe #

Bilder bekommen automatisch einen dekorativen Hintergrund mit Schatteneffekt für bessere Optik.

Wenn ein Bild einen eigenen Hintergrund hat (z. B. durch Brandbird), kann der automatische Hintergrund mit “no-background” abgeschaltet werden:

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

Nutze "no-background", wenn dein Screenshot schon seinen eigenen Rahmen/Boden hat.

UI-Referenzen #

Das Knowledge Center wird automatisch übersetzt, daher referenzieren wir Menüpunkte mit einem speziellen Shortcode.

Syntax:

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

Für Referenzen in Überschriften ist die Syntax etwas anders:

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

Die Ausgabe wird als fettgedruckter Text angezeigt und bleibt in allen Sprachen gleich: Search > Designs > New Design > Omnisearch

Callouts #

Das sind farbige Boxen zur Hervorhebung wichtiger Punkte. Sie sollten sparsam eingesetzt werden und nur, wenn etwas besonders relevant ist.

Das heißt auch, dass ein Artikel im Allgemeinen nicht mehr als 1 Callout pro Typ enthalten sollte.

Syntax:

{{< hint info|warning|danger >}}
**Something**: To be aware of.
{{< /hint >}}

Es gibt drei Typen:

Info zu etwas, das man wissen sollte – z. B. unser Vorschlag für ein Einstiegstemplate.

Warnung vor etwas, das zu einem Problem werden könnte – z. B. das Nicht-Speichern vor dem Verlassen einer Seite.

Gefahr bei Dingen, die das Setup zerstören könnten – z. B. ein Upgrade ohne voriges Backup.

Nutze sie wirklich nur bei Bedarf und je nach Wichtigkeit der Information.

Codeblöcke #

Sie gibt es inline und als Block.

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

Codeblöcke als Block werden mit 3 Backticks zu Beginn und Ende und der Sprache für Syntax-Highlighting erstellt:

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

Schreib los! #

Jetzt bist du bereit, Inhalte der Spitzenklasse zu schreiben!

Es gibt viel zu verarbeiten, wahrscheinlich vergisst du morgen die Hälfte. Mach eine Pause, iss etwas Gutes und lies nochmal darüber.

Such dir dann im Knowledge Center einen Artikel, den du verbessern möchtest und schreibe ihn nach diesen Vorgaben neu. Halte diesen Leitfaden dabei immer offen für Rückfragen.

Bittest du am Ende noch eine:n Kolleg:in um Feedback – das dauert keine 10 Minuten – können blinde Flecken entdeckt werden, die dir selbst unbemerkt geblieben wären.

Jeder bekommt beim Schreiben Tunnelblick. Feedback ist entscheidend für den besten Content.

Viel Spaß beim Schreiben!