Blog

Darstellung des Artikels:

       

2021-03-16

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

Dieses Smart-Information-Blitzlicht 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.

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.

Bringt Sie das auf Ideen, Ihren Altdatenbestand nach HTML zu konvertieren oder konvertieren zu lassen? Sprechen Sie mit uns!

*

In unserer Blitzlicht-Reihe zeigen wir Smart-Information-Blogger in unregelmäßigen Abständen, kurz und knackig, was Smart-Information heute schon in der Praxis heißt.

Get in touch

c-rex.net GmbH
DE-78259 Mühlhausen-Ehingen
Phone: +49 7733 503636
Fax: +49 7733 503634
Email:info@c-rex.net
Web:http://www.c-rex.net

We have decades of experience in dealing with organisations of all sizes in the fields of technical communication and publishing industries.
Get the best results with our services (not only in the cloud).

Send us an e-mail

Or follow us on social media

Copyright c-rex.net GmbH, DE-78259 Mühlhausen-Ehingen © 2021
Data Processing At Its Best