From a bulky 7000 page PDF to a well usable webhelp

Black and white photo of five people leafing through a very thick book

This blog post tells the story of how we took a very large specification that existed as a set of individual Word and PDF documents and put it into a form that was usable by developers. Take a look at our implementation. We will show you how we have eliminated the main deficits of the initial situation with manageable effort. We think we have succeeded quite well. But look for yourself!

Starting position unsmart: Complicated use of an extensive spec

In our day-to-day development work, we often deal with conversion to and from Microsoft Word. To do this, we work a lot with ECMA-376, the OOXML specification. Anyone who has ever had access to this ~7000 page collection of information knows that it is very troublesome to work with this specification in PDF, Word, or say, the printed documents.

When working with the specification, it is especially important that information is found quickly. Try to open the Word Part IV from Edition 1 only. It takes an average of 5 minutes for the document to be displayed. Now try to search in this extensive document. You will see that it takes some time again until the search is active and responds. The situation is similar with the PDF versions. This is not a state that developers who need quick access to a particular piece of information can live well with.

Target smart: Easy access to info from the spec

That's where you want the presentation and fast access to all information and ideally in a fully responsive layout, with a good way to navigate the content, with syntax highlighting and of course a fast full text search.

Conversion to a webhelp, HTML5

To realize these goals, the conversion of the specification to HTML5 was the obvious choice. How fortunate that we have a conversion environment designed for just such tasks.

So we configured our own conversion environment, c-rex.net.DTS, to extract all the information from the Word and bring this content to DITA and from there to a web help that meets all the requirements for our day-to-day business. This conversion was done completely automatically.

Correct, the intermediate format is DITA. And with that, we are on our way in a structured and, above all, modularized way. The world is open - from machine translation to user-driven content delivery based on iiRDS, for example. By the way, the DITA content is available for download at c-rex.net resources.

Screenshot of the ECMA Spec as webhelp. Callout show the different areas of help: Table of contents, index, favorites, comment function, full text search.

Highlights of Webhelp compared to the PDF solution of the original ECMA Spec

Here you can see the highlights, that is, what we think makes working with the spec in HTML format much smarter than working with the Word or PDF versions.

Representation

responsive vs. non-responsive in Word

Search

Full text search vs. limited to the respective Word file
Search suggestions in the search box
Search duration a few seconds vs. several minutes in 5000-page file
Ranking of search results vs. no ranking of search results in Word

Content navigation and orientation

via total and chapter tables of contents vs. Table of contents only at the beginning of the Word file

Syntax highlighting

Syntax highlighting vs. no syntax highlighting in Word

Nobody is perfect: the little quirks of HTML implementation

We are aware that this fully automatic conversion does not provide a perfect result. And it doesn't have to! But we'll come back to that in a moment. Here we show you some shortcomings in the conversion result, but we developers can easily live with them.

superfluous colons in some elements, e.g. Notes and Example
lack of chapter numbering especially when there are references that show the section number rather than the title text.

Conclusion: Focusing on the essentials and ignoring details that are not important for the use case

This project is a good example of a project implementation in which we did not start from the maximum feasible, but implemented a solution based on a very specific use case.

We have deliberately refrained here from an attitude that we have observed time and again: The tendency to be perfect, to get hung up on a lot of little things that generate a lot of effort. All too often, this results in a project taking far too long to implement. Or it may cause the attention to detail to derail projects altogether.

With the OOXML-Spec, we have a special use case: A reference book for developers who need to work with Word For this use case, it is important that information can be found quickly. developers - the target group of this implementation - are not really interested in the small quirks described above. If I, as a developer, can get to the result with a few clicks, it quickly helps me with my day-to-day business and I'm happy that I no longer have to struggle with Word or bulky non-responsive PDFs.

So we generated a real added value for developers here with a not 100% approach and with manageable effort, because we simply didn't care about the details mentioned. Of course, if it's important for other use cases, you can invest more time and money to optimize the result even further.

If you like, take a look at the result yourself: OOXML example on the c-rex.net site.