Gute Gründe für Web Manuals

Es ist viel schwieriger, Komplexität zu reduzieren, als etwas Einfaches von Grund auf neu zu schaffen. Aber jemand muss es tun.

Es gibt fast immer den einen, „richtigen Weg“, etwas zu tun.

Und wenn es richtig gemacht wird, wird das Endergebnis schön, klar definiert und eine Freude für die Sinne sein.

Man muss diesen richtigen Weg nur im Meer aller möglichen Konfigurationen finden.

1. Gute Gründe für Web Manuals

Wenn Ihr Unternehmen gut gestaltete, ansprechende High-End-Produkte herstellt und vertreibt, werden Ihre Kunden sich dazu auch Anleitungen wünschen, welche die Ästhetik und Philosophie Ihrer Marke widerspiegeln. Sie werden vielleicht nicht explizit danach verlangen. Aber sie werden definitiv die Dissonanz zwischen einem hochwertigen Produkt auf der einen und schlecht gemachter, schwer lesbarer Dokumentation auf der anderen Seite bemerken.

Schauen wir uns an, wie sich solch eine frustrierende Benutzererfahrung vermeiden lässt.

1.1 Warum nicht bei PDF-Anleitungen bleiben?

Ein veraltetes Publishing-Konzept

Viele Hersteller von Consumerprodukten stellen ihre Anleitungen immer noch als herunterladbare PDFs zur Verfügung. Lassen Sie uns darlegen, warum dies ein problematischer Ansatz ist.

PDFs sind letzten Endes „digitales Papier“.

PDF (das „Portable Document Format“) ist ein auf dem Konzept der (gedruckten) Seite basierendes Format, das vor über 30 Jahren entwickelt wurde – für eine Welt, in der vor allem mit Papier, Faxgeräten und Briefpost gearbeitet wurde.

Dies ist aber nicht mehr die Welt, in der die meisten Menschen heute leben.

Ein PDF hat immer …

• eine feste physische Größe (A4, A5, US Letter…),
• ein unveränderliches Seitenverhältnis
• eine sich daraus ergebende Ausrichtung (Hochformat, Querformat, quadratisch).

Im Leben der meisten Menschen dominieren heute – im Jahr 2025 – hingegen leichte Smartphones, Tablets, Notebooks und (am anderen Ende des technischen Spektrums) hochwertige, hochauflösende 4K- / 5K-Bildschirme.

Dies führt zu einem erstaunlichen Spektrum an Displaygrößen und Auflösungen. Man beachte zum Beispiel den Faktor (≥ 50), der zwischen den 0,165 MP eines Smartwatch-Displays und einem 8,2 MP Ultra-HD-Bildschirm (3840 × 2160 Pixel) liegt.

Kein Dokument mit fester Größe – egal, wie schön und gut gestaltet es auch sein mag – lässt sich so stark skalieren. Daher werden Ihre Anwender auf mobilen Geräten ein- und auszoomen und mühevoll in einem solchen Dokument navigieren müssen. Und das wird ihnen wahrscheinlich nicht gefallen.

Ein „brüchiges“ Anwendererlebnis

Heutzutage ist davon auszugehen, dass die meisten Ihrer Kunden und Partner vor allem im World Wide Web veröffentlichte Informationen – also HTML-Dokumente – lesen und verarbeiten. Dementsprechend ist ihr Webbrowser die Lese- und Arbeitsumgebung, in der sie sich am besten auskennen und am wohlsten fühlen. Viele Anwender maßschneidern diese Umgebung auch mit Erweiterungen und angepassten Tastenkombinationen.

Es kann für Benutzer frustrierend sein, wenn sie eine Dokumentation erst einmal in einem Binärformat wie PDF herunterladen – und dann einer separaten Anwendung oder dem PDF-Anzeigemodul öffnen müssen. Das gilt besonders für technisch weniger versierte Anwender.

Der PDF-Viewer auf einem handelsüblichen Smartphone wiederum hat möglicherweise völlig andere Funktionen, Steuerelemente und eine andere Darstellungs- / Rendering-Qualität als der Browser – und in der Regel wird die Benutzererfahrung hier schlechter ausfallen.

1.2 Welche Probleme gibt es bei älteren Dokumentenformaten und Layout-Anwendungen?

Wenn vorhandene Anleitungen aktualisiert werden müssen (beispielsweise nach Firmware-Updates) müssen oft inhaltlich veraltete Dokumente in nicht mehr aktuellen Formaten „ausgegraben“ werden, was zu Verzögerungen, zusätzlicher Arbeit und Mehrkosten führt.

Viele bekannte und beliebte Marken existieren schon seit Jahrzehnten. Dasselbe gilt dementsprechend für ihre Anleitungen.

Und da kein Unternehmen gerne Geld in die Pflege historischer Dokumente steckt, sind viele dieser älteren Anleitungen heute inhaltlich und gestalterisch „Inseln“, die nicht mehr dem aktuellen Anspruch der Marke genügen. Sie existieren oft nur als verborgene Ordner auf der Festplatte eines Grafikdesigners, in denen Dutzende Versionen von Word- oder InDesign-Dateien und Illustrationen liegen. Nicht immer ist gewährleistet, dass all diese im Lauf der Jahre und Jahrzehnte erstellten Dokumente von Autoren und Mediengestaltern noch geöffnet und aktualisiert werden können.

Das Ergebnis sind dann oft Sammlungen von PDF-Dateien, die stark veraltet oder zumindest inkonsistent aussehen. Und wahrscheinlich wollen Sie nicht, dass jemand Ihre Marke mit einer solchen „Dokumentenscheune“ in Verbindung bringt.

1.3 Datensilos machen allen Stakeholdern das Leben schwer

Oft umfasst das Problem historisch gewachsener Datensammlungen mehr als nur veraltete PDFs. In den meisten Unternehmen sind die Produktinformationen auf verschiedene „Datensilos“ verteilt: geschlossene Dateiformate, Speichersysteme oder Plattformen. Sie machen das Erstellen, Aktualisieren und Übersetzen von Inhalten unnötig schwer. Außerdem sind Vertriebe, Händler und Endanwender gezwungen, zwischen diesen Systemen hin und her zu springen, wenn sie nach bestimmten Informationen suchen.

Ein offener, formatunabhängiger Ansatz für die Dokumentation hat Vorteile, die sich sofort bemerkbar und sehr schnell bezahlt machen:

• Alle Autoren von Inhalten können dasselbe Toolset zum Erstellen und Aktualisieren von Inhalten verwenden.
• Die Übersetzung wird effizienter, da das verwendete Übersetzungsmanagementsystem nur noch einen Wiedergabe abbilden muss.
• Sowohl Endnutzer als auch Suchmaschinen finden alle relevanten Informationen an einem Ort.

2. Die naheliegende Lösung: HTML

2.1 HTML hat die (Publishing-)Welt erobert

Die Grundlagen des World Wide Web – HTML, CSS und JavaScript – sind ein bewährtes Toolset für nahezu jedes denkbare Format: Nachrichten, Marketing-Sites, soziale Medien, wissenschaftliche Arbeiten … und natürlich auch Produktdokumentation.

2.2 Web Manuals, FAQs, Kurzanleitungen usw. sind bereits weit verbreitet

Beispiele:

• Apple iPhone Anleitung
• Adobe Photoshop Anleitung
• Mercedes EQE Benutzerhandbuch
• Teenage Engineering OP-1 Anleitung

2.3 HTML + CSS = stabil und skalierbar

Mit sorgfältig vorbereiteten Vorlagen und Responsive Stylesheets sind Web Manuals auf Geräten aller Art und Größe gut lesbar und attraktiv. Und das gilt sowohl für ältere und aktuelle wie auch zukünftige Produkte.

2.4 Web Manuals sind vollwertige Webseiten

Web Manuals sind aus technischer Sicht HTML-Dateien, ergänzt durch CSS und (optional) JavaScript. Unternehmen, die ihre Anleitungen als Web Manuals veröffentlichen, profitieren sofort vom erfolgreichsten Technologie-Stack der Welt – und damit natürlich auch von all dem Geld und dem Know-how, das über die Jahrzehnte in die Entwicklung von Browsern, Rendering-Engines und Indexierungstechnologien investiert wurde.

2.5 Optimal für die Suchmaschinenoptimierung

Web Manuals sind letzten Endes normale Webseiten. Dementsprechend können Suchmaschinen sie leicht lesen und verarbeiten – was bedeutet, dass die Investition in dieses Format die Sichtbarkeit relevanter Produktinformationen erhöht.

2.6 Ideal für Ihre Kunden und Geschäftspartner

Inhalte, die leicht zu finden und leicht zu lesen sind, machen nicht nur Endkunden, sondern auch anderen Stakeholdern das Leben leichter:

• Distributoren (die von maschinell übersetzbaren Inhalten profitieren, auch wenn sie nicht die Kosten für die Lokalisierung der Dokumentation übernehmen wollen
• Händler (für die es nun einfacher ist, technische Informationen sowohl zu neuen als auch älteren Produkten zu finden)
• Support-Mitarbeiter (die Benutzer nun direkt zu den relevanten Informationen leiten können, anstatt ihnen zu sagen „Das steht irgendwo in der Anleitung“)
• all die anderen Institutionen und Personen, mit denen Sie zusammenarbeiten (zum Beispiel Journalisten, externe Entwickler, Normungsorganisationen …), die schon genug Arbeit und Probleme auf dem Tisch haben.

Eine Lösung, mit der Sie allen Beteiligten die Arbeit beziehungsweise die Produktnutzung erleichtern und außerdem viel Geld sparen können: Diese Entscheidung sollte Ihnen leichtfallen.

2.7 Gut geeignet für Nutzer mit Sehbehinderungen / ältere Nutzer

Web Manuals sind HTML-Dokumente. Das bedeutet, dass sie von speziellen Bildschirmlesegeräten oder -anwendungen und dem Lesemodus moderner Browser problemlos verarbeitet werden können. Dies ist ideal für Benutzer, die Schwierigkeiten haben, Texte in sehr kleinen Schriften (die berühmt-berüchtigten „Bleiwiesen für Ameisen“ in PDFs) zu lesen. Dies ist besonders hilfreich für Benutzer, die Schwierigkeiten haben, kleine Texte zu lesen.

2.8 Kostenlose Übersetzung

Es ist ein offenes Geheimnis, dass die Qualität der maschinellen Übersetzung mittlerweile mit der von professionellen menschlichen Übersetzern konkurrieren kann – nicht überall und immer, aber doch bei vielen Sprachpaaren, Dokumenttypen und Branchen.

• Auch moderne Browser verfügen inzwischen über integrierte Funktionen zur maschinellen Übersetzung. Das bedeutet, dass Sie sich selbst bei (älteren) Handbüchern, bei denen Sie kein Geld für die Übersetzung ausgeben wollen, darauf verlassen können, dass Chrome, Safari & Co. Übersetzungen Ihrer Web-Handbücher in die meisten relevanten Zielsprachen in akzeptabler oder sogar hervorragender Qualität liefern werden.

• Es ist auch möglich, serverseitige Links zu erstellen, die Nutzer über die Website translate.google.com direkt zu maschinell übersetzten Versionen einer Seite weiterleiten.

2.9 Einfach zukunftskompatibel

HTML wird nie verschwinden – nun, zumindest nicht in den nächsten 20 oder 30 Jahren. Und selbst wenn es in Zukunft neuere HTML-Versionen geben sollte, sorgen Milliarden von Webseiten dafür, dass zukünftige Browser jahrzehntelang rückwärtskompatibel bleiben werden.

Granularität

Sie haben diesen Begriff vielleicht noch nie gehört, aber Granularität ist eine Wirklich Wichtige Sache™. ☺️

Granularität stellt sicher, dass in einem komplexen Dokument oder Kompendium kleine, relevante Fragmente (der eine Satz mit der einen Information, nach der Ihre Benutzer verzweifelt gesucht haben) leicht identifiziert und mit einem Standard-Web-Mechanismus, den Fragment-URLs, aufgerufen werden können.

Einfach ausgedrückt: Wenn eine Frage immer wieder gestellt wird, müssen Ihre Support-Mitarbeiter die nach Rat suchenden Anwender in Zukunft nicht mehr mit Hinweisen auf „die Website“ oder „das Handbuch“ vertrösten – sondern können diese Anwender direkt auf einen bestimmten Satz in einem bestimmten Absatz in einem bestimmten Kapitel eines bestimmten Handbuchs verweisen / verlinken. Präziser geht es kaum.

3. Semantische Dokumentation

Es ist (mit einem gewissen Mehraufwand für Autoren und Programmierer) möglich, in Web Manuals maschinenlesbare Nutzdaten im JSON-LD-Format zu integrieren. Google, Bing und andere Suchmaschinen / Content-Indexer können diese Informationen verarbeiten und sie den Endanwendern direkt zur Verfügung stellen, was das Leben aller Beteiligten erleichtert.

Außerdem kommen nun auch noch neue innovative Suchmaschinen wie Perplexity ins Spiel, die künstliche Intelligenz nutzen, um Antworten direkt auf der Ergebnisseite zu liefern. Diese Suchmaschinen nutzen semantische (also maschinenlesbar strukturierte) HTML-Quellen, die es ihnen ermöglichen, relevante Informationen zu extrahieren und den Anwendern Zeit zu sparen.

All das wird ermöglicht durch die Magie des semantischen Webs:

Nutzer (und Maschinen) können Fragen wie „Welche Abmessungen hat dieses Gerät?“ stellen – und erhalten nicht nur einen Link zu einer Seite, sondern konkrete Daten – direkt auf der Ergebnisseite der Suchmaschine. Einfacher geht es nicht.

4. „Aber wir brauchen auch in Zukunft PDFs für unsere Marke!“

Und die sollen Sie auch bekommen. 😊

Mithilfe von Print CSS können aus HTML-Dokumenten ansprechende, druckfähige PDFs erstellt werden.

Dies ist eine „kostenlose“ / eingebaute Funktion moderner Browser. Der Benutzer muss dazu nur auf Drucken beziehungsweise „Als PDF speichern“ klicken.

Um eine bessere Qualität zu erzielen und anspruchsvolle Benutzer zufriedenzustellen, können HTML-Handbücher auch auf dem Server konvertiert werden, um „traditionelle“ herunterladbare PDFs zu erstellen.

Hier gibt es zwei Möglichkeiten:

1. „Headless“-Konvertierung mit der PDF-Engine eines generischen Webbrowsers.
2. Kommerzielle HTML- / XML-zu-PDF-Konverter: Dies führt insbesondere bei komplexen Dokumenten zu noch besseren Ergebnissen, erfordert aber eine aufwändigere Konfiguration, Tests und Lizenzgebühren für die Konvertierungs-Engine.

5. Grundlegende Prinzipien

5.1 Wir mögen es DRY („Don’t repeat yourself“)

Obwohl Specs and Docs ein relativ neuer Dienst ist, haben wir unseren Arbeitsablauf und unsere Kerntechnologie über einen langen Zeitraum hinweg entwickelt. Dabei haben wir im Lauf der Entwicklung viele unnötig komplexe Elemente entfernt, um sicherzustellen, dass das resultierende System für eine lange Zeit nutzbar ist.

Auf diese Weise vermeiden wir jede unnötige Komplexität:

6. Die Schönheit von Markdown

Markdown ist eines der weltweit beliebtesten „Dateiformate“ beziehungsweise Auszeichnungssprachen. Weitere Informationen finden Sie zum Beispiel unter de.wikipedia.org/wiki/Markdown. Es ist ein hervorragendes Basisformat für Produktliteratur, also zum Beispiel Bedienungsanleitungen, Kurzanleitungen, FAQs und alles andere, was Ihre Marke benötigt.

6.1 Einfaches textbasiertes Markup

Markdown ermöglicht es Autoren, mit sehr wenigen Zeichen – beispielsweise Bindestrichen und dem Rautenzeichen # – alle relevanten Elemente in einem Dokument zu formatieren / auszuzeichnen:

• Struktur (Überschriften, Listen),
• Betonungen / Hervorhebungen,
• Illustrationen,
• Tabellen,
• Links,
• Fußnoten usw.

6.2 Leicht zu lesen und zu schreiben

Markdown ist eine Art digitales Esperanto, das von Menschen leicht interpretiert und von Computern gut verarbeitet werden kann.

Die Kernkonzepte von Markdown können selbst von technisch nicht versierten Benutzern in etwa zehn Minuten erlernt und angewendet werden.

6.3 Keine „Programmierung“, keine zwingend erforderlichen Tools, keine Softwarelizenzen

Ein beliebiger Texteditor, wie es ihn für jedes Betriebssystem gibt, reicht aus. Außerdem existieren viele Online-Tools zum Erstellen und Konvertieren von Markdown-Dateien.

Markdown wird auch in GitHub und vielen Content-Management-Systemen verwendet.

Für fortgeschrittenere Anwendungen gibt es viele Erweiterungen der Basis-Syntax von Markdown:

• Dokumentenabschnitte,
• Fragment-IDs,
• Mathematische Formeln,
• Zitate
• usw.

7. „Schön. Aber warum machen wir das alles nicht gleich in unserem CMS?“

7.1 Ein Content Management System ist keine gute Umgebung für die Erstellung von Langtexten

Ein typisches Content-Management-System „von der Stange“ ist nicht die richtige Umgebung zum Schreiben und Strukturieren umfangreicher technischer Inhalte. Mit unserem Markdown-basierten Ansatz hingegen können Ihre technischen Redakteure, Entwickler, Produktmanager und alle anderen Beteiligten auf einfache Weise Produktliteratur erstellen, ändern und kommentieren, ohne spezielle Software verwenden oder auf Ihre Content-Publishing-Plattformen zugreifen zu müssen. Dokumente können sogar mit Messaging-Apps oder einem der zahlreichen webbasierten Teamworking-Tools verschickt und bearbeitet werden, ohne dass es Konvertierungsprobleme gibt oder erst Zugriffsrechte vergeben werden müssen.

7.2 Sicherheitsüberlegungen

Wenn Sie mit externen Autoren, Korrektoren und Übersetzungsdienstleistern zusammenarbeiten, möchten Sie ganz sicher nicht, dass all diese Personen und externen Unternehmen im Backend Ihres Content-Management-Systems herumspazieren und dort Zugriff auf Dinge haben, die sie wahrscheinlich nicht sehen (und ändern) sollen.

Wenn Sie als Ihrem Workflow nicht durch zusätzliche „Gatekeeper“ unnötig kompliziert machen wollen, ist es wahrscheinlich am besten, beide Welten (Web-Publishing und Dokumentation) getrennt zu halten.

7.3 „Mapping“ von Sprachen

Die auf Ihrer Website und in anderen Marketingkanälen verwendeten/unterstützten Sprachen stimmen möglicherweise nicht mit den Sprachen überein, in denen Sie Ihre Produktdokumentation bereitstellen wollen.

Dazu ein Beispiel.

Ihr Unternehmen betreibt Websites für vier Regionen in vier Sprachen, die sich in der jeweiligen Top-Level-Domain befinden:

• yourbrand.com (Englisch)
• yourbrand.de (Deutsch)
• yourbrand.fr (Französisch)
• yourbrand.dk (Dänisch)

Nun möchten Sie Ihre Anleitungen und andere Dokumente auf Englisch, Deutsch, Französisch, Spanisch, Portugiesisch und Koreanisch zur Verfügung stellen (jedoch nicht auf Dänisch, da Sie wissen, dass Ihre dänischen Benutzer auch mit einer Dokumentation in englischer Sprache zufrieden sein werden).

Wie stellen Sie nun Ihre Dokumentation den einzelnen Zielgruppen zur Verfügung? Die Sprachverwaltungsfunktionen eines Content-Management-Systems haben Grenzen. An einem bestimmten Punkt werden Sie es mit einem schwer zu pflegenden „gordischen Knoten“ aus Sprachen zu tun haben. Aus diesem Grund ist es wahrscheinlich eine gute Idee, die Zielsprachen für den das Marketing (Website, Social-Media-Kanäle usw.) und für Produktliteratur getrennt zu halten.

7.4 PDF-Erstellung und Druck

Die meisten Content-Management-Systeme (die ja für das Erstellen und Veröffentlichen von hochmodularen Webseiten optimiert wurden) bieten „out of the box“ keine Unterstützung für die Erstellung ansprechend gestalteter PDFs aus Langtexten. Möglicherweise erlauben sie den Ausdruck einer Seite, und möglicherweise sieht diese Seite dann auch ansprechend aus – aber dies erfordert immer Mehrarbeit auf Seiten Ihrer Designern und/oder Ihrer Web-Agentur.

Mit unserem Workflow können sich Ihre Geschäftspartner und Käufer auf Anleitungen zugreifen, die auf dem Bildschirm gut aussehen und darüber hinaus in nüchterne und sauber formatierte umgewandelt werden können. Die Anwender können dann gegebenenfalls nur die Informationen drucken, die sie gerade benötigen, ohne eine Menge Tinte für nicht benötigte Bilder und Kapitel zu verschwenden.

8. Deliverables

Wenn Sie uns mit der Konvertierung, Strukturierung und dem „Rendering“ Ihrer Dokumentationsinhalte für das Web beauftragen, bekommen Sie von uns die folgenden Assets und Dienstleistungen:

8.1 Konvertierung Ihrer bestehenden Dokumentation in das Markdown-Format

Bitte beachten Sie: Während praktisch alle weiteren Schritte in unserem Workflow automatisiert beziehungsweise automatisierbar sind, ist dies in der Regel manuelle, zeitaufwändige und komplexe Arbeit – und bevor wir hierfür ein Angebot abgeben können, müssen wir uns mit den entsprechenden Ausgangsdateien beschäftigen.

8.2 Zugriff auf einen Konvertierungsserver

… mit allen installierten / benötigten Softwarekomponenten.

8.3 Markdown-Quelldateien

… für alle Ihre Anleitungen, Kurzanleitungen, FAQs usw., wie sie uns zur Verfügung gestellt werden.

8.4 YAML-Konfigurationsdateien

… mit Metadaten und Variablen, die unter anderem sicherstellen, dass Ihre Handbücher valides HTML und korrekt miteinander verlinkt sind.

8.5 CSS für Ihre Anleitungen

… damit Ihre Anleitungen dem Corporate Design Ihres Unternehmens entsprechen.

8.6 Maßgeschneiderte Templates für Ihre Anleitungen

Specs-and-Docs-Templates umfassen „Logik“ – das heißt Variablen (beispielsweise „consumer product: true“ oder „Europe only: true“), die so ausgewertet werden, dass am Ende maßgeschneiderte Publikationen entstehen, die nur die für Ihre Zielgruppe relevanten Informationen enthalten.

8.7 Gerenderte HTML-Anleitungen

Web Manuals sind letzten Endes valide, statische HTML5-Dateien, ergänzt durch einige wenige semantische CSS-Klassen und (optional) ein paar Zeilen JavaScript. Diese HTML-basierten Anleitung können entweder von uns oder durch Ihr Unternehmen online bereitgestellt werden – Sie haben also beim Hosting die Wahl.

8.8 Gerenderte PDF-Anleitungen

Unsere Anleitungen sind mit einem Standard-Stylesheet für den Ausdruck beziehungsweise die PDF-Erzeugung ausgestattet, das alle beim Druck störenden Elemente und Formatierungen entfernt und ein sauberes, nüchternes Layout erzeugt. Ihre Kunden und Geschäftspartner können diese Anleitungen dann direkt aus ihrem Webbrowser drucken, ohne unnötig Tinte oder Toner zu verschwenden. Es bleibt genug Leerraum auf den Seiten für persönliche Notizen. Stylesheets für den Druck (beziehungsweise die Erstellung von PDFs) können auch individuell angepasst werden – zum Beispiel, wenn Ihre Marke oder Ihre Branche ein kompakteres, papiersparendes Layout bevorzugt.

Darüber hinaus bieten wir optional an, PDFs serverseitig oder offline zu rendern.

↻ 2025-08-21