Von einem sperrigen 7000-Seiten-PDF zu einer gut nutzbaren Webhelp

Schwarzweiß-Foto, auf dem fünf Personen in einem sehr dicken Buch blättern

Dieses Blogbeitrag erzählt, wie wir eine sehr umfangreiche Spezifikation, die als Set von einzelnen Word- und PDF-Dokumenten vorlag, in eine für EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen brauchbare Form gebracht haben. Werfen Sie einen Blick auf unsere Umsetzung. Wir zeigen Ihnen, wie wir mit überschaubarem Aufwand die Hauptdefizite der Ausgangslage behoben haben. Wir meinen, das ist uns ganz gut gelungen. Aber schauen Sie selbst!

Ausgangslage unsmart: Erschwerte Nutzung einer umfangreichen Spec

In unserem Entwickleralltag beschäftigen wir uns häufig mit der Konvertierung von und nach Microsoft Word. Dazu arbeiten wir viel mit der ECMA-376, der OOXML-Spezifikation. Wer jemals Zugang zu dieser ~7000 Seiten umfassenden Informationssammlung hatte, weiß, dass es sehr lästig ist, mit dieser Spezifikation in PDF, Word oder etwa mit den gedruckten Dokumenten zu arbeiten.

Bei der Arbeit mit der Spezifikation ist es vor allem wichtig, dass Informationen schnell gefunden werden. Versuchen Sie einmal aus der Edition 1 das Word-Dokument Part IV nur zu öffnen. Es dauert im Schnitt 5 Minuten, bis das Dokument angezeigt wird. Versuchen Sie nun, in diesem umfangreichen Dokument zu suchen. Sie werden sehen, dass es nochmals einige Zeit dauert, bis die Suche aktiv ist und reagiert. Ähnlich verhält es sich mit den PDF-Versionen. Das ist kein Zustand, mit dem EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen, die schnell Zugriff auf eine bestimmte Information benötigen, gut leben können.

Zielvorstellung smart: Leichter Zugriff auf Infos der Spec

Da wünscht man sich die Darstellung und den schnellen Zugriff auf alle Informationen und idealerweise in einem voll responsiven Layout, mit einer guten Möglichkeit in den Inhalten zu navigieren, mit Syntaxhervorhebung und natürlich einer schnellen Volltextsuche.

Umsetzung in eine Webhelp, HTML5

Um diese Ziele zu realisieren, bot sich die Konvertierung der Spezifikation nach HTML5 an. Wie gut, dass wir eine Konvertierungsumgebung haben, die genau für solche Aufgaben gedacht ist.

Wir haben also unsere eigene Konvertierungsumgebung c-rex.net.DTS so konfiguriert, dass sie alle Informationen aus dem Word-Dokument extrahiert und diese Inhalte nach DITA und von dort in eine Web-Hilfe bringt, die alle Anforderungen für unser Tagesgeschäft erfüllt. Diese Konvertierung wurde vollständig automatisch durchgeführt.

Richtig, das Zwischenformat ist DITA. Und damit sind wir strukturiert und vor allem modularisiert unterwegs. Die Welt steht offen – von der maschinellen Übersetzung bis hin zum user-getriebenen Content Delivery beispielsweise auf Basis von iiRDS. Der DITA Content steht übrigens unter c-rex.net resources zum Download zur Verfügung.

Screenshot der ECMA Spec als Webhelp. Callout zeigen die verschiedenen Bereiche der Hilfe: Inhaltsverzeichnis, Index, Favoriten, Kommentarfunktion, Volltextsuche.

Highlights der Webhelp im Vergleich zur PDF-Lösung der Original ECMA Spec

Hier sehen Sie die Highlights, also das, was unserer Ansicht nach das Arbeiten mit der Spec im HTML-Format deutlich smarter macht, als das Arbeiten mit den Word- oder PDF-Versionen.

Darstellung

responsive vs. nicht responsive im PDF/Word

Suche

Volltextsuche vs. begrenzt auf die jeweilige PDF-/Word-Datei
Suchvorschläge im Suchfeld
Suchdauer wenige Sekunden vs. mehrere Minuten in 5000-Seiten-Datei
Ranking der Suchergebnisse vs. keine Bewertung der Suchergebnisse in PDF/Word

Inhalts-Navigation und Orientierung

über Gesamt- und Kapitel-Inhaltsverzeichnisse vs. Inhaltsverzeichnis nur am Anfang der PDF-/Word-Datei

Syntaxhighlighting

Syntaxhervorhebung vs. keine Syntaxhervorhebung in PDF/Word

Nobody is perfect: die kleinen Macken der HTML-Umsetzung

Uns ist klar, dass diese vollautomatische Konvertierung kein perfektes Ergebnis liefert. Und das muss es auch nicht! Aber darauf kommen wir gleich noch einmal zurück. Hier zeigen wir Ihnen einige Defizite im Konvertierungsergebnis, mit denen wir EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen aber leicht leben können.

überflüssige Doppelpunkte bei einigen Elementen, z.B. bei Notes und Example
fehlende Kapitelnummerierung vor allem, wenn es Verweise gibt, die nicht den Titeltext, sondern die Abschnittsnummer anzeigen.

Fazit: Konzentration auf das Wesentliche und Ignorieren von Details, die für den Usecase nicht wichtig sind

Dieses Projekt ist ein gutes Beispiel für eine Projektrealisierung, bei der wir nicht ausgehend vom maximal Machbaren, sondern ausgehend von einem ganz speziellen Usecase eine Lösung umgesetzt haben.

Wir haben hier ganz bewusst von einer Haltung Abstand genommen, die wir immer wieder beobachten konnten: Der Tendenz perfekt zu sein, sich an vielen Kleinigkeiten aufzuhängen, die sehr viel Aufwand generieren. Das führt allzu oft dazu, dass es viel zu lange braucht, bis ein Projekt umgesetzt ist. Oder es führt dazu, dass die Detailverliebtheit Projekte vielleicht sogar ganz zum Scheitern bringt.

Mit der OOXML-Spec haben wir einen speziellen Usecase: Ein Nachschlagewerk für EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen, die mit Word arbeiten müssen. Für diesen Usecase ist es wichtig, dass Informationen schnell gefunden werden. EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen – also die Zielgruppe dieser Umsetzung – interessieren die oben beschriebenen kleinen Macken nicht wirklich. Wenn ich als EntwicklerEntwicklerinEntwickler und EntwicklerinEntwickler:in mit ein paar wenigen Klicks zum Ergebnis komme, hilft mir das schnell bei meinem Tagesgeschäft und ich bin happy, dass ich mich nicht mehr mit Word oder sperrigen nicht-responsiven PDFs herumschlagen muss.

Wir haben hier also mit einem nicht 100%-Ansatz und mit überschaubarem Aufwand einen richtigen Mehrwert für EntwicklerEntwicklerinnenEntwickler und EntwicklerinnenEntwickler:innen generiert, weil uns die genannten Details einfach egal waren. Wenn es für andere Anwendungsfälle wichtig ist, kann man natürlich auch mehr Zeit und Geld investieren, um das Ergebnis noch weiter zu optimieren.

Wenn Sie mögen, schauen Sie sich das Ergebnis selbst an: OOXML-Beispiel auf der c-rex.net-Seite.