Repco and DITA at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

Gareth Oakes walked us through a case study of an automotive content management system that he designed and implemented in collaboration with Repco. The content is stored and managed in DITA format, and published on a website.

Overview of the system: Autopedia

Repco supplies automotive parts in Australia and New Zealand, dealing with retailers as well as their workshop division. They were founded in Australia in 1922. The system is called Autopedia, a subscription product for mechanics and workshops. It provides automotive service and diagnostic information for the majority of vehicles on the road in Australia. For example, diagnostic codes, wiring diagrams, procedures for replacing timing belts, and so on.

Autopedia is a replacement for an “encyclopedia” in the form of a CD that was mailed out to the mechanics. The content was written by Repco technical writers. It was becoming more and more difficult to keep up with the number of vehicles, and variations of vehicle, on the road. It was expensive to maintain the content. And customers wanted online content, not CDs.

Designing a solution

Repco came up with a vision for a replacement system, and Gareth’s team worked with them on the technical solution.

A summary of what the solution comprised:

Content (Repco & third party) -> DITA -> DITA CCMS -> HTML -> Web server

(CCMS = Component Content Management System. The team uses the Arbortext Content Manager.)

The team wrote a multiple conversion pipeline, consisting of a set of Java tools, to convert the content into DITA format. A vehicle mapping table related the vehicle models in other countries to the Australian models. At first this required a lot of quality control, but now it’s up and running it doesn’t need so much attention.

Creating and storing the content

All content is stored as a simple DITA topic. The aim was to keep the system simple. Each topic is tagged to indicate which vehicle it applies to. Other semantics are added when required to support the needs of website display. This was done iteratively, as the need arose. For example, in a voltage table you may want certain values to stand out.

Repco content makes up only 1% of the content. Repco now authors all new content in DITA, using Arbortext Editor. Third-party content come from a vendor in the USA, in multiple formats: database, CSV, custom XML, images. The automatic process converts all this to DITA topics, grouping the topics by vehicle applicability. The system then does a diff process and sends only what’s changed to the web.

Delivering the content

All content is converted to HTML and sent to the web server (Umbraco). The vehicle mapping table is used to decide where the content belongs in the navigation structure. Images are hosted on a CDN (Content Delivery Network) hosted by Rackspace. Topics are marked as published or unpublished on the web service, so separating the publication process from the content storage and update process, and allowing the publishing process to respond quickly to customer feedback.

Project timeline

In all, the project took approximately 9 months. The team was reasonably small: approximately 9 people across the various teams at both GPSL (where Gareth works) and Repco.

(Members of the audience at Gareth’s session expressed surprise at and admiration for the short timeframe of this project.)

The initial design sessions with Repco took approximately a month. The other phases included planning sessions with the web team, development of the code and the vehicle mapping table (which took around 6 months), and migration of existing content to DITA. Then following integration of all the components, and testing. Documentation, training and knowledge transfer was important. Then the initial conversion and content upload took a while – more than 200GB. Then came the go live date, and ongoing support.

Results of the launch

The project launched late in 2012. The response from the market was very positive. They achieved their revenue goals and ROI well within the first year. Most existing customers migrated to the new system, and more than 1000 new customers signed up.

A few project notes

DITA was a good solution for this system, using basic topics and a very light layer of specialisation for vehicle tagging. The team may need to add more specialisation in future, based on customer demands for dynamic representations, such as decision tables. A next step may be a live link to parts, so that the parts are ready when you come in to work the next day. The single sourcing aspect is extremely useful. Store the content in one place and be able to output in many formats, such as PDF. The team found DITA easy to work with, as there are many tools available.

You need a level of skill with XML. DITA also very much steers you to author your content as topics, which may not suit every solution. You may also need new tools. And with a laugh, Gareth said that you risk turning into one of those DITA fans who runs around recommending DITA as a solution for everyone else. 🙂

The huge amount of content caused many delays, which were not entirely expected. The information structure required a number of design changes during development, due to the complexity of vehicle classification. The DITA CCMS required a lot of specific configuration and optimisation to ensure it was performing as required.

Conclusion

Thank you Gareth for an insight into a very interesting project and a cool system.