Die versteckte Komplexität der Bereitstellung technischer Dokumentation im Web

Hinweis: Dieser Blogbeitrag wurde mithilfe von KI aus der Originalversion übersetzt und kann daher geringfügige Abweichungen enthalten. Einige der Links in diesem Beitrag führen zu Inhalten, die nur auf Englisch verfügbar sind.

Dokumentation im Web zu veröffentlichen ist komplexer, als es scheint. Zu glauben, es gehe einfach darum, HTML-Seiten zu erzeugen und auf eine Website hochzuladen, ist naiv und führt so gut wie sicher zu einer schlechten Nutzererfahrung und letztlich zum Scheitern.

Jahrzehntelang wurde technische Dokumentation in Form gedruckter Bücher und Ordner ausgeliefert, verfasst von einem kleinen Team und zusammen mit dem Produkt in Kartons verschickt. Dieser Ansatz ist inzwischen überholt. Mit dem Aufkommen von Computern entwickelten sich gedruckte Ordner zu ihrer dematerialisierten Version: dem PDF. Unternehmen kopierten diese Dateien dann auf USB-Sticks oder CDs und verschickten sie in Kartons, wodurch die Druckkosten auf die Kunden abgewälzt wurden. Mit dem Aufstieg des Internets in den 1990er-Jahren entstand die Möglichkeit, diese Dateien auf einem FTP-Server zu hosten, sodass Nutzer sie bei Bedarf herunterladen konnten. Mit der Reifung des Webs machten Unternehmen dieselben Dateien schließlich über Websites zugänglich.

Doch nicht nur das Format hat sich verändert, sondern auch die Teams, die an der Erstellung der Dokumentation beteiligt sind:

• Gedruckte Handbücher wanderten in einem sequenziellen Prozess von technischen Redakteuren (sowie Fachexperten und Prüfern) zu Druckereien und dann zur Logistik.
• Bei PDFs arbeiten technische Redakteure und die IT-Abteilung (Information Technology) mit überlappenden Aktivitäten und Verantwortlichkeiten zusammen. Das Redaktionsteam ist häufig dafür zuständig, Dateien in einer von der IT geschaffenen und gepflegten Infrastruktur zu aktualisieren.

So einfach diese Verschiebung auch erscheinen mag, sie enthält bereits alle Ansätze und Anzeichen der kommenden Transformation und Komplexität.

Mit Blick auf die wichtigsten hier wirkenden Kräfte – Dokumentationsformat, Bereitstellungsmedium und Teams – können wir die Zwischenstufen der Dokumentation (einschließlich E-Books, CHM) überspringen und uns der Gegenwart sowie der Einführung moderner Technologien zuwenden: strukturiertem Authoring, HTML-Formatierung und Web-Bereitstellung.

Heute sind sich immer mehr Menschen des Werts technischer Dokumentation bewusst und wissen, wie stark ein angemessener Zugriff darauf die Support-Effizienz und Kundenzufriedenheit beeinflusst. Gleichzeitig sind mehr Stakeholder beteiligt – Marketing, Kundensupport, User Experience und weitere –, die Input liefern, Einfluss nehmen oder sogar mitentscheiden, wie Dokumentation im Web präsentiert wird. Doch nur wenige dieser Stakeholder verstehen die zugrunde liegende Komplexität der Web-Veröffentlichung und bieten ineffiziente Lösungen an, die häufig zum Scheitern von Projekten führen.

Die Bereitstellung technischer Dokumentation im Web ist komplex und birgt zahlreiche Fallstricke und Herausforderungen:

• Struktur und Granularität
• Organisation und Auffindbarkeit
• Stakeholder, Design und Tools

Werden diese Herausforderungen mit modernen Technologieplattformen berücksichtigt und bewältigt, eröffnet dies den Weg zu einer reibungsloseren, reichhaltigeren Nutzererfahrung sowie zu einem effizienteren und profitableren Geschäftsergebnis.

Herausforderungen bei Struktur und Granularität

Selbst bei einer komponentenbasierten Authoring-Strategie wird Dokumentation nach wie vor primär als eine Abfolge von Erzählungen verstanden, organisiert in Dokumenten, Referenzhandbüchern und Handbüchern. Die Herausforderung besteht hier im Übergang von einem Dokument, das als durchgängiger Fluss von Sätzen und Absätzen dargestellt wird, zu einer Reihe einzelner Webseiten.

Bei der Erzeugung eines PDFs gibt es hierzu nichts zu überlegen: Die Granularität entspricht dem Dokument, die Komponenten werden zu einem einzigen Strom zusammengefügt, und die Seitenaufteilung wird durch das Papierformat vorgegeben. Wird dieselbe Dokumentation jedoch auf HTML-Seiten abgebildet, gibt es viele konkurrierende Optionen. Sie könnten beispielsweise für jedes Dokument eine einzige HTML-Seite erstellen, genau wie bei einem PDF. Alternativ könnten Sie für jede Komponente eine eigene Seite erzeugen oder eine Zwischenlösung wählen, etwa eine HTML-Seite pro Kapitel, Abschnitt oder Unterabschnitt.

Jeder Ansatz hat Vor- und Nachteile: Ein als einzelne HTML-Seite dargestelltes Dokument lässt sich leichter navigieren (einfach durchscrollen), kann jedoch im Browser quälend lange zum Laden brauchen. Eine Seite, die nur eine einzige Inhaltskomponente enthält, lädt dagegen schnell, führt aber zu mühsamer Navigation – dem Albtraum der Vor-/Zurück-Buttons – und den Nutzern fehlt womöglich der Kontext für die Information, auf die sie zugreifen. Das kann für Nutzer besonders lästig werden, wenn kleine Themen speziell zur Optimierung der Content-Wiederverwendung konzipiert wurden.

Diese Entscheidung über die Seitengranularität ist entscheidend, da sie erheblichen Einfluss auf die Endnutzererfahrung sowie auf die Effizienz beim Auffinden und Lesen von Informationen hat.

Hinzu kommt die Herausforderung der Suchrelevanz. Suchmaschinen indexieren Inhalte auf der gewählten Granularitätsebene. Bei einer einzigen HTML-Seite pro Dokument liefert jede Suchanfrage all diese langen, keyword-lastigen Dokumente als Ergebnis. Diese Suchergebnisse sind wahrscheinlich irrelevant, und der Nutzer muss das gesamte Dokument erneut durchsuchen. Enthalten die Seiten dagegen nur eine einzige Komponente und gibt der Nutzer mehrere Keywords ein, wird möglicherweise gar kein Ergebnis geliefert, da die gesuchten Begriffe über verschiedene Komponenten und damit verschiedene Seiten verteilt sein könnten. Eine gängige Lösung besteht darin, eine mittlere Granularität zu wählen, um die Suche relevant genug zu machen und eine positivere Nutzererfahrung zu bieten.

Doch dies schafft wiederum andere Probleme im Hinblick auf Bewertungs-, Feedback- oder Lesezeichenfunktionen. Die mittlere, grobkörnige Ebene mangelt es an Präzision und untergräbt den Nutzen dieser feingranularen Funktionen. Ähnlich verhält es sich bei präzisen Analysen: Je länger die Seite, desto weniger genau wissen Sie, was Nutzer tatsächlich lesen.

Zudem kann sich die passende Seitengranularität je nach Inhaltstyp unterscheiden. Artikel oder Tipps zur Fehlerbehebung könnten beispielsweise als einzelne Seite dargestellt werden, während ein Referenzhandbuch effektiv „zerlegt“ werden könnte. Diese Granularität könnte sich sogar dynamisch je nach Nutzerpräferenzen oder verwendetem Gerät ändern. Was auf einem Laptop oder Mobilgerät ausgeliefert wird, könnte sich von dem unterscheiden, was als Online-Hilfe oder in einer AR-Brille angeboten wird.

Der entscheidende Punkt ist: Auch wenn es technisch trivial ist, eine Reihe von HTML-Seiten zu erzeugen, ist an der Darstellung von Dokumentation als HTML nichts Einfaches. Moderne Content-Delivery-Technologien können jedoch die Komplexität von Struktur und Granularität bewältigen. Sie können Inhaltsfragmente, wie sie in Ihrem Autorentool vorliegen, dynamisch zusammensetzen, um virtuelle HTML-Seiten einer bestimmten Größe gemäß festgelegten Regeln zu erzeugen. Content Delivery Platforms (CDPs), wie unsere eigene bei Fluid Topics, erzeugen keine HTML-Seiten im Voraus. Sie bewahren die Granularität der Inhalte und bauen die Seite erst im Moment der Anzeige zusammen. Dadurch variiert die tatsächliche Größe der HTML-Seite je nach Inhaltstyp, Nutzer oder Gerät – und genau das unterscheidet ein Web-CMS klar von einer CDP.

Herausforderungen bei der Content-Organisation

Technische Dokumentation ist kein beliebiger Inhalt. Sie spiegelt die gesamte Produktlinie eines Unternehmens wider, die häufig verschiedene Versionen, eine Vielzahl von Anpassungen und unzählige Optionen umfasst, mitunter übersetzt in mehrere Sprachen, um ein globales Publikum zu bedienen. Selbst die generischsten Installationshandbücher existieren daher wahrscheinlich in einem Dutzend verschiedener Varianten.

Die verschiedenen Varianten desselben Inhalts zu strukturieren und zu organisieren, ist bereits eine eigene Herausforderung. Hier müssen wir uns entscheiden zwischen der Erstellung einer Zwischenseite mit allen Varianten des Dokuments und der Erstellung eines Navigationsbaums, bei dem die Varianten auf verschiedene Seiten verteilt sind.

oder

Und das ist nur für ein einziges Handbuch. Jedes Produkt einer Reihe verfügt wahrscheinlich über mehrere spezifische Handbücher und Leitfäden. Kommen mehrere Produktlinien über verschiedene Produktkategorien hinweg hinzu, steigt die Komplexität nur weiter. Dies wirft Fragen danach auf, wie die für jedes Dokument sowie für alle Varianten dieses Dokuments erzeugten HTML-Seitensätze am besten organisiert werden. Entscheider müssen daher die optimale Superstruktur wählen (also die Zwischenebenen der Navigationsseiten), auf der aufgebaut werden soll. Diese Strukturen sind schwierig zu entwerfen und zu pflegen, da laufend neue Produkte hinzukommen, alte entfernt werden, Produktlinien umorganisiert und neue Versionen erstellt oder veraltete abgeschafft werden.

Im in Abbildung 4 gezeigten Beispiel möchte die Nutzerin auf die in der gelben Komponente enthaltene Information zugreifen. Von der Startseite aus müsste sie sich durch mehrere Zwischenseiten klicken, um ihre Produktlinie, ihr Produkt, den Typ, die Version usw. zu finden, das richtige Dokument aufzurufen und sich weiterzuklicken, bis sie die richtige Seite findet. Ein mühsamer, fehleranfälliger und ineffizienter Prozess.

Wie zu sehen ist, kann eine derart komplexe Seitenhierarchie unglaublich schwer zu navigieren sein. Angesichts der Komplexität der Verwaltung solcher Hierarchien mag man sich fragen, warum solche Navigationsstrukturen überhaupt verwendet werden.

Es gibt drei Haupterklärungen:

1. Es ist unbewusst: Es ist eine Website, und seit den Anfängen des Webs bestehen Websites aus verlinkten Seiten, die häufig hierarchisch organisiert sind.
2. Es ist historisch: Die erste Dokumentations-Website eines Unternehmens, auf der klassische PDFs gehostet wurden, verfügte über diese Navigationsstruktur, um zu den Seiten zu verlinken, auf denen jedes PDF gespeichert war. Als HTML-Seiten diese PDFs ersetzten, behielt die Website ihre übergeordnete Navigationsstruktur bei.
3. Es ist erzwungen: Das für das Hosting und die Veröffentlichung der HTML-Seiten gewählte Tool setzt standardmäßig eine Baumstruktur voraus.

Alternativ kann sich ein Unternehmen dafür entscheiden, suchgetrieben statt navigationsgetrieben vorzugehen.

• Navigationsbasiert: Ein erheblicher Aufwand fließt in die Organisation aller Inhalte in einer Baumstruktur. Nutzer müssen sich durchklicken, bis sie ihr Ziel finden. Siehe die Abbildung links in Abbildung 5 unten.
• Suchgetrieben: Der Haupteinstiegspunkt zu Inhalten ist für den Nutzer die Eingabe einer Suchanfrage, gegebenenfalls mit Filtern zur Eingrenzung der Suche, und der Klick auf ein Ergebnis, um zur gewünschten Information zu gelangen. Siehe die Abbildung rechts in Abbildung 5 unten.

Diese beiden Ansätze standen schon immer im Widerspruch zueinander, besonders im Kontext des Webs. Als in den frühen 1990er-Jahren die ersten Websites entstanden, konnten Nutzer sie über Verzeichnisse wie Yahoo finden und aufrufen. Sie navigierten durch Seiten, die Websites nach Themen und Unterkategorien organisierten. Mit der Zeit wurde es zunehmend schwieriger, diese Taxonomien aufzubauen und zu pflegen, und die Nutzer begannen, sich im weiten Web zu verlieren. Und dann kam Google. Kategorisierungen und Taxonomien wurden durch eine einzige weiße Seite mit einem Suchfeld ersetzt – und das Webverzeichnis war tot.

Angesichts dieser Geschichte ist es merkwürdig, dass Unternehmen weiterhin Aufwand in die hierarchische Organisation von Inhalten stecken. Möglicherweise fehlt es an geeigneter Suchtechnologie, die diesen Übergang ermöglicht. Dennoch sollten wir Navigationsseiten nicht vollständig hinter uns lassen. Das wird deutlich, wenn man die beiden unterschiedlichen Nutzermotivationen betrachtet:

• „Zeig mir, was es gibt“: Neue Nutzer stöbern gerne. Sie möchten Informationen entdecken, verstehen, wie sie organisiert sind, und sie mit ihrem bestehenden Wissen abgleichen. Das Navigieren durch organisierte Seiten hilft ihnen, ihr Verständnis zu vertiefen.
• „Ich brauche diese Information“: Erfahrene Nutzer bevorzugen die Suche. Sie kennen das Produkt und den Umfang der Dokumentation. Sie rufen das Portal auf, um ein Problem zu lösen oder eine Antwort zu finden. Sie haben keine Zeit, sich mit Irrelevantem aufzuhalten, und je weniger Klicks nötig sind, desto besser ist die Erfahrung.

Bei der Veröffentlichung von Inhalten im Web ist es wichtig, beiden Motivationen gerecht zu werden und für beide eine passende Lösung bereitzustellen. Einen Navigationsbaum aufzubauen reicht nicht aus, und eine erstklassige Suche ist unverzichtbar. Die gute Nachricht: Ein einziger Aufwand kann beides effektiv gleichzeitig adressieren:

1. Nutzen Sie den Navigationsbaum als implizite Taxonomie. Diese Zwischenseiten und -ebenen wie Produktlinien, Produkte, Typen, Varianten, Versionen und Sprachen sind Metadatenwerte, die alle zur Kennzeichnung von Inhalten verwendet werden können. Dadurch wird Ihre implizite Sortierstrategie zu expliziten Content-Tags.
2. Indexieren Sie die Inhalte und Metadaten mit einer Suchmaschine, die all diese Tags nutzt, um erfahrenen Nutzern Filter bereitzustellen (auch als facettierte Suche bekannt), und gleichzeitig spezifischere Funktionen wie das dynamische Gruppieren von Content-Varianten ermöglicht (auch als Clustering bekannt).
3. Erstellen Sie Navigationsseiten mithilfe der Suchmaschine. Diese Seiten können dynamisch sein und auf Suchanfragen basieren; zum Beispiel kann eine Seite, die Produktlinien und Produkte auflistet, tatsächlich aus Suchergebnissen erzeugt werden. Seiten müssen nicht manuell gepflegt werden, ungültige Links werden vermieden, und Zugriffsrechte bleiben gewahrt, sodass Nutzer auf diesen Navigationsseiten nur das sehen, wozu sie berechtigt sind. Ist die Suchmaschine gut genug, ermöglicht sie die Darstellung von Navigationsseiten, die für den jeweiligen Nutzer personalisiert sind und Ergebnisse sowie Inhalte basierend auf seinem individuellen Profil und seinen Präferenzen anzeigen.

Herausforderungen bei Stakeholdern, Design und Tools

Heute verstehen mehr Menschen als je zuvor den Wert technischer Dokumentation und möchten daran beteiligt sein – wenn nicht sogar vollständig darüber entscheiden –, wie und wo Dokumentation im Web platziert wird.

Das „Wo“ ist ein Anliegen der Stakeholder, die technische Dokumentation intensiv nutzen und sie möglicherweise in ihrer eigenen Arbeitsumgebung verfügbar haben möchten. Denken Sie zum Beispiel an das Kundensupport-Team. Seine Aufgabe ist es, Kundenanfragen zu beantworten und offene Fälle rasch zu lösen, um optimale Kundenzufriedenheit sicherzustellen. Sein wichtigstes Tool ist die Service-Desk-Software, denn dort landen Nutzer, wenn sie ein Problem haben, das sie selbst nicht lösen können. Entsprechend behauptet ein Kundensupport-Team häufig, dass ein eigenes Portal für technische Dokumentation nicht der richtige Ort für deren Veröffentlichung sei, da dies nur einen weiteren Touchpoint schaffe; stattdessen solle die technische Dokumentation „im Helpdesk“ verfügbar sein. Das ist eine nachvollziehbare Entscheidung im Hinblick auf die Customer Journey, doch bei einer strengen Auslegung des Ausdrucks „im Helpdesk“ entsteht ein Problem.

Technische Dokumentation im Helpdesk verfügbar zu machen, um Case Deflection und eine schnelle Fallbearbeitung zu unterstützen, bedeutet nicht, dass der Inhalt selbst in das Helpdesk-Tool geladen werden sollte. An einem Ort verfügbar zu sein bedeutet nicht, dort zu „wohnen“ – besonders dann nicht, wenn das Tool dafür nicht gebaut ist. Helpdesk-Tools können Wissensdatenbank-Artikel erstellen und verwalten – HTML-basierte Einzelinhalte, die grob getaggt werden können. Diese Funktion wurde für Support-Mitarbeiter entwickelt, um schnelle Antworten auf wiederkehrende Fragen zu erstellen.

Sie kann und sollte jedoch nicht dazu verwendet werden, technische Dokumentation zu hosten – indem vorab erzeugte HTML-Seiten technischer Inhalte zwangsweise als Wissensdatenbank-Artikel geladen werden. Die Komplexität von Granularität und Struktur technischer Dokumentation macht es unmöglich, sie effektiv auf eine flache Liste unverbundener Artikel abzubilden. Jede daraus resultierende Nutzererfahrung – ob beim Suchen oder Navigieren – wird katastrophal ausfallen, und aus dem Versuch, das Leben der Nutzer zu vereinfachen, wird es nur noch schwieriger gemacht.

Die angestrebte Nutzererfahrung lässt sich jedoch erreichen, indem die technische Dokumentation von einer Content Delivery Platform gehostet und ausgeliefert wird, mit einer Live-Verbindung über APIs zwischen dem Helpdesk und der CDP. Genau für diese Multichannel-Bereitstellungsebene mit Headless-Fähigkeiten ist eine CDP gebaut.

Wenn das Kundensupport-Team also die Verantwortung für die Bereitstellung technischer Dokumentation übernehmen möchte, seien Sie darauf vorbereitet, Widerstand zu leisten, zu erklären und den kollaborativen Weg aufzuzeigen: Das Team für technische Dokumentation sollte die CDP verantworten, das Kundensupport-Team den Helpdesk.

Ähnlich könnten auch die Marketing- oder UX/UI-Design-Teams versuchen, die Kontrolle über die technische Dokumentation zu übernehmen. Da technische Dokumentation live im Web verfügbar ist, größere Sichtbarkeit bei einer breiten Nutzerschaft gewinnt – und über SEM-SEO-Maßnahmen (Search Engine Marketing und Search Engine Optimization) zur Markenbekanntheit beiträgt – fühlt sich das Marketing zu Recht dafür verantwortlich, sein Wissen und seine Praktiken auf die technische Dokumentation anzuwenden.

Ein Marketing-Team könnte vorschlagen – oder sogar durchsetzen –, die eigenen bestehenden Tools zur Bereitstellung von Inhalten zu verwenden, meist ein Web-CMS, das für die Unternehmenswebsite genutzt wird, wie WordPress, AEM, Drupal oder Contentstack. Aus all den zuvor genannten Gründen – Granularität, Struktur sowie Navigation versus Suche – ist dies nicht ideal und führt lediglich zu einer schlechten Nutzererfahrung. Als Experten für technische Inhalte wird es Ihre Aufgabe sein, dies zu erklären.

Auch auf der Design-Seite wird es zusätzliche Anforderungen geben: Branding, Seitenlayout, Navigation und mehr. Bei der Reaktion auf diese Designanforderungen ist es wichtig, den Wald vor lauter Bäumen nicht aus den Augen zu verlieren. Die technische Dokumentation am Corporate Branding auszurichten ist eine Sache – die Benutzeroberfläche zu überdesignen eine ganz andere. Denken Sie daran, dass der Inhalt der Star der Seite sein sollte und das Leseerlebnis stets im Vordergrund stehen muss. Halten Sie das Design einfach, unkompliziert und effizient. Überladen Sie die Oberfläche nicht, versuchen Sie, das Navigationslabyrinth zu reduzieren, stellen Sie Suche und Relevanz in den Mittelpunkt, denken Sie über eine responsive Oberfläche nach, priorisieren Sie Barrierefreiheit und setzen Sie auf Personalisierung.

Es ist wichtig sicherzustellen, dass die CDP all diese Entscheidungen unterstützen kann, einschließlich der Tools, um ein Doku-Portal ohne aufwendige individuelle Webentwicklung aufzubauen – denn diese wird andernfalls schnell zu einer Belastung bei der Pflege und einem langfristigen Altlastenproblem. Low-Code ist heute unverzichtbar, und damit können Sie eine nahtlose Journey schaffen, indem Sie dasselbe Single Sign-on (SSO) und dasselbe Branding nutzen, sodass Nutzer den Wechsel von der Unternehmenswebsite zum Doku-Portal gar nicht bemerken.

Zudem ist es wichtig, Marketing- und Design-Teams daran zu erinnern, dass technische Dokumentation kein beliebiger anderer Inhalt ist. Sie wird erstellt, um Nutzer bei der Verwendung und Wartung von Produkten zu schulen und zu unterstützen. So wie Menschen früher mit papierbasierten Inhalten interagierten, indem sie Text markierten, Notizen an den Rand schrieben und Haftnotizen an Seiten anbrachten, muss auch technischer Content ähnliche Funktionen bieten. Das ist etwas, das weder ein Web-CMS noch ein Helpdesk-Tool noch individuelle Software bereitstellen: Es handelt sich um zentrale Funktionen, die Nutzer erwarten und die eine dedizierte, speziell dafür entwickelte CDP liefern kann.

Schließlich wird das IT-Team fast sicher weitere Anforderungen an die technische Dokumentation stellen. Es erwartet die Möglichkeit, die CDP mit anderen Tools in der Unternehmensinfrastruktur zu verbinden, und das Infosec-Team wird Sicherheitsgarantien fordern. Egal wie leistungsstark und funktionsreich ein Tool auch sein mag – es wird nicht eingeführt werden, wenn es das Unternehmen einem Cyberangriffsrisiko aussetzt. Dies wiederum erhöht die Anforderungen und die Komplexität der Bereitstellung technischer Dokumentation im Web.

Fazit

Wir leben in aufregenden Zeiten, in denen technische Dokumentation in vielen Unternehmen zu einem zentralen Thema wird und damit die Chance auf radikale Transformation und operative Effizienz eröffnet.

Doch technische Dokumentation ins Web zu bringen bedeutet nicht einfach, HTML-Seiten zu erzeugen und eine Website zu erstellen. Es ist deutlich komplexer, erfordert spezifische Tools, die dieser Komplexität gerecht werden, und verlangt, alle Anforderungen und Perspektiven einer neuen Gruppe von Stakeholdern zu unterstützen und in Einklang zu bringen. Teams für technische Dokumentation müssen darauf vorbereitet sein, dieser Komplexität souverän zu begegnen, und ihre Stakeholder auf die Vorteile vorbereiten, die eine effiziente und effektive Umsetzung mit sich bringt.

Anmerkung der Redaktion: Dieser Artikel wurde ursprünglich im März 2023 im tcworld-Magazin veröffentlicht.