DITA - One Success Story to Share

I’d like to share a recent project with you that I think may provide a solution to problems you’re facing in publishing tech comm content using Drupal. This is my first post on Drupal.org after registering two days ago, so bear with me as I tell you the [somewhat long] story of how I used Drupal to solve the problem of publishing technical documentation online.

I’ve been working and teaching in tech comm for over 20 years. I recently directed a large (40-person) technical communication team producing software and hardware documents for users and system admins for a telecommunications company. I was hired to lead the team, but also to improve quality and transform the delivery method to HTML. This story focuses only on the HTML delivery portion.

Tackling the Transformation from PDFs to HTML Books

Like any project, this one began by collecting requirements. My team initially provided a long, writer-oriented list, which included things like managing, tracking, and sharing writing and visual components, two-way integration between source and published versions, and one-button publishing. The company requirement was quite simple -- deliver HTML-based Web documents that can be easily found and viewed on any device.

For years, the team had been using Adobe FrameMaker, and to a lesser extent MS Word, to publish documentation as PDFs posted to the company support site for download. While PDFs make desktop printing easy, they often require long download times and can’t be read on small screen devices. PDFs also prevent the ability to collect any useful search or display analytics critical in measuring content effectiveness. I knew switching to responsive HTML-based Web books would solve this.

Although I knew there were proprietary CMS products available, I also knew they were expensive and often lacked all of the capabilities I knew were needed. The vision I set was to make HTML delivery the main delivery method for all customer-facing product documentation using a CMS that provided the freedom to customize and innovate.

To simplify the project, I focused initially on a way to process native Frame and Word files into HTML-based books. I chose Drupal as the Web CMS for its economics and flexibility. The book module provided a basic way for navigating multi-page documents and views provided ways to associate collections of relevant tagged content.

Successful 2013 Launch

The initial requirements took roughly two years to complete and launched in early 2013. On the authoring side, it required developing new doc templates that a strictly enforced style formatting (read: structured authoring) across the client applications. It required development of a taxonomy model that could support all the various products, document types, versions, and other supporting documents. And, it required developing a user interface that would expose the features and functionality, be easy to use, and be easily brandable for marketing purposes.

On the Drupal side, we ended up with a navigation model based loosely on the book module. The entire project incorporates roughly 250 new and/or modified Drupal modules. These include scripting modules to clean up source XHTML output from the client applications, as well as others to handle style-mapping, issues management, and content workflow to name a just a few.

This solution is capable of quickly transforming a complex 1,200-page native Word or Frame document into a responsive “Web book” format that’s optimized for low bandwidth devices. It also inherently supports publishing DITA XML, as the structure is well-suited. "Among the first documents published are this admin guide...

http://plcmtechnet.com/documents/en/voice/ucs/5-0-1/administrators-guide...

...which began as a 600-page Word document, and this admin guide...

http://plcmtechnet.com/documents/en/realpresence/realpresence-collaborat...

... which began as a Frame file at twice that length.

Other Technical Wins

Besides delivering HTML books, the solution also includes printing and language support. To maintain print capabilities and offline content viewing, it includes automatically generated PDFs. This was done by integrating Drupal with PDF Reactor which can be extended to support geographic-specific page sizes, ebooks, and epub versions.

For language support, it will also generate PDFs from either vendor-translated or Google Translated language versions which are incorporated into the UI. In this instance, this feature essentially pays for the ongoing annual hosting, maintenance, and resource costs.

My mission now is to expand this solution to support more native file types and help others transition from print/PDF-based delivery models to HTML-based publishing on the both the authoring and publishing sides of the fence. I hope I’ve inspired you to make Drupal your tech comm publishing solution and I’d be happy to try and answer any questions around this.

Cheers,
Steve (steve@definio.ca)