Blog Archives

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.

STC Summit day 2 – Using DITA

I’m at STC 2012, the annual conference of the Society for Technical Communication. This post contains my notes from a session called “Using DITA”, by Michael Priestley, lead DITA architect at IBM.

Michael started off by telling us what DITA is and giving us some historical background.

What is DITA and who is using it?

DITA (Darwin Information Typing Architecture) is an open standard for designing, creating and publishing modular information, such as technical publications, help sets and websites. The standard is owned by OASIS. It was originally created for technical communication, but was designed to be more broadly applicable. We are starting to see other types of content adopt the DITA standard now too, such as learning and training. As a result, some LMS systems are now adapting to support DITA too.

The latest DITA standard, OASIS DITA 1.2, was approved in December 2010.

A public survey at ditawriter.com conducted a survey and found that around 250 companies have posted public case studies. Breaking the usage down by industry sector, around 30% of companies that use DITA are in the software sector. Geographically, the largest number of DITA users is in North America, followed by Europe.

In technical communication, a survey in 2008 found that DITA was the most popular standard, at 35%.

Michael discussed some case studies from around 2008-9,including the reasons why the companies adopted DITA :

  • Avaya adopted DITA to solve problems of low-quality for globalised content, inconsistency in content and style, and problems in training new writers. They reported improvements in these areas, as well as increased user satisfaction and happier writers,
  • CaridianBCT adopted DITA to reduce translation costs. They reported savings of $100,000 in the first year.
  • Medtronic needed to improve productivity. The metrics quoted were based on the amount of content that the team managed to produce using the new reuse model.
  • WebSphere adopted DITA for content reuse in the documentation for their application server product. They report 80% reuse of their content across the entire set. Note that the percentage of reuse required depends on the amount of commonality across the different products.

Smart content

Michael discussed a study by the Gilbane Group, called “Smart Content in the Enterprise”. One of the most interesting aspects was a shift from an inward-facing to an outward-facing view of the content. Focus on what the users need from the content, and on delivery as the starting point of design.

The core elements are providing metadata, integrating social systems with the content, and using structured content as the source.

Getting practical – DITA topics and maps

DITA is all about chunks of content called topics. This concept has nothing to do with reuse. It’s all about content use. With all types of content other than novels, people jump in and out of a book or manual to find what they need. They don’t read the book from start to finish. What we must do is understand what the user needs to do, and prioritise that over the needs of the product.

Here Michael took us through the core elements of DITA:

  • The high-level structure of a topic in DITA.
  • An example of a DITA map. A map does all the referencing and organising. You would have a map per output format.
  • A map in topic links.
  • A map with generated navigation and links. The build process takes the information in the map, and turns it into a table of contents and supported linking patterns.

Conditional processing

Michael showed us the underlying DITA tags for conditional processing. We don’t assert that you should include or exclude something. Instead, we assert that it applies to a specific product or products.

Then you set conditions as part of the build process, to include or exclude products, or to flag specific content.

Conref

In some cases, you want to reuse a fragment of a topic or a fragment of a map. In those cases, you would use a conref.

A conref is basically an empty element that instructs the build process to pull in the content from another element at publication time.

Note that you should do this as little as possible. In most cases, you would use conditional processing to include or exclude a topic. Reason: If people change a paragraph, it could mess up your content reuse. Topics are a more basic unit of structure, and so are less subject to breaking changes.

Information typing

The idea is that different types of information are best served by different structures. What’s more if a particular type of information is presented in a particular structure, that will help the user understand the information.

DITA defines a specific set of structures for tasks. For example

  • Prerequisites
  • Steps
  • Warnings

Each of the above elements has sub-elements, and rules about what can go where. The task  is a type of topic. You can use a task anywhere that you would use a topic. The task has rules unique to it. We call this “specialisation”.

What’s new in DITA 1.2?

  • Taxonomies. Michael showed us the big vision of how his team uses taxonomies to provide progressive disclosure from the product UI to the web-based user assistance.
  • Learning and training specialisations.

What’s coming in DITA1.3?

The group is working to provide a lighter-weight DITA editing experience, for technical communicators and other DITA users too.

Michael’s presentation style is easy and authoritative. Thank you Michael for an informative insight into DITA.

Converting documents between a wiki and Word, XML, FrameMaker or other help formats

This week I published a post on the Atlassian blog about single source publishing on a wiki. I’m cross-posting it here because it may be useful to technical writers who read this blog. :)

The post discusses a few of the reasons why we may want to write our documents on a wiki and then publish them to other formats, or conversely write the documents using another tool and then publish them to a wiki as one of the delivery formats.

Next, the post recommends some good tools for converting content from these formats into Confluence wiki format:

  • From Microsoft Word to Confluence wiki
  • From Adobe FrameMaker to Confluence wiki
  • From DITA XML to Confluence wiki

And some tools for converting content from a Confluence wiki into these formats:

  • From Confluence to PDF
  • From Confluence to Microsoft Word
  • From Confluence to HTML
  • From Confluence to XML (Confluence-specific format)
  • From Confluence to DocBook XML
  • From Confluence to Eclipse Help
  • From Confluence to JavaHelp

In case it’s useful, there’s also a post I wrote a while ago about getting content into and out of wikis. That post looks at a couple of other wikis as well as Confluence, and covers a wider range of tools. The new post on the Atlassian blog is more up to date and is specifically about conversion tools to and from Confluence.

If you’re interested, mosey on over to the Atlassian blog and take a look. I’d love to hear your experiences with the tools mentioned in the blog post, or if you’ve used any other tools or need any other conversions. What did I miss out? There’s an interesting discussion going on already. Here’s the link again: Technical writing in a wiki – single source publishing.

AODC Day 3: Introduction to DITA Conditional Publishing

A couple of weeks ago I attended AODC 2010, the Australasian Online Documentation and Content conference. We were in Darwin, in Australia’s “Top End”. This post is my summary of one of the sessions at the conference and is derived from my notes taken during the presentation. All the credit goes to Dave Gash, the presenter. Any mistakes or omissions are my own.

This year’s AODC included a number of useful sessions on DITA, the Darwin Information Typing Architecture. I’ve already written about Tony Self’s session, an update on DITA features and tools, and about Suchi Govindarajan’s session, an introduction to DITA.

Now Dave Gash presented one of the more advanced DITA sessions, titled “Introduction to DITA Conditional Publishing”.

At the beginning of his talk, Dave made an announcement. He has presented in countries all over the world, many times, and he has never ever ever before done a presentation in shorts!

AODC Day 3: Introduction to DITA Conditional Publishing

AODC Day 3: Introduction to DITA Conditional Publishing

Introducing the session

To kick off, Dave answered the question, “Why do we care about conditional processing?” One of the tenets of DITA is re-use. You may have hundreds or even thousands of topics. In any single documentation set, you probably don’t want to publish every piece of the documentation every time.

Conditional processing is a way to determine which content is published at any one time.

Dave’s talk covered these subjects:

  • A review of DITA topics, maps and publishing flow
  • The use of metadata
  • The mechanics of conditional processing
  • Some examples

Metadata and the build process

Dave ran us through a quick review of the DITA build process and the concept of metadata. Metadata has many uses. Dave talked specifically about metadata for the control of content publication.

Metadata via attributes

There are a number of attributes available on most DITA elements. These are some of the attributes Dave discussed:

  • audience – a group of intended readers
  • product – the product name
  • platform – the target platform
  • rev – product version number
  • otherprops – you can use this for other properties

Example:

<step audience="advanced">

Using metadata for conditional processing

Basically, you use the metadata to filter the content. For example, let’s assume you are writing the installation guide for a software application. You may store all the instructions for Linux, Windows and Mac OS in one file. When publishing, you can filter the operating systems and produce separate output for each OS.

In general, you can put metadata in these 3 locations (layers):

  • maps – metadata on the <map> element. You might use metadata at this layer to build a manual from similar topics for specific versions of a product.
  • topics – metadata to select an entire topic. You might use metadata at this layer to build a documentation set for review by a specific person.
  • elements – metadata on individual XML elements inside a topic. You might use this metadata to select steps that are relevant for beginners, as opposed to intermediate or advanced users.

Dave gave us some guidelines on how to decide which of the above layers to use under given circumstances.

Defining the build conditions to control the filtering

Use the ditaval file to define the filter conditions. This file contains the conditions that we want to match on, and actions to take when they’re matched. The build file contains a reference to the ditaval file, making sure it drives the build.

Dave talked us through the <prop> element in the ditaval file, and its attributes:

  • att – attribute to be processed
  • val – value to be matched
  • action – action to take when match is found

A hint: You can use the same attribute in different layers (map, topic and element). Also, you don’t need to specify the location. The build will find the attributes, based on the <prop> element in the ditaval file.

Next we looked at the “include” and “exclude” actions. Remember, the action is one of the attributes in the <prop> element, as described above. Here’s an example of an action:

<prop att="audience" val="novice" action="exclude" />

Dave’s recommendation, very strongly put :) is:

Don’t use “include”. Stick to “exclude”.

The basic rule is: Everything not explicitly excluded is included.

Dave’s final recommendation

Go get DITA and play with it!

My conclusion

It was great to have a focus on the conditional publishing side of DITA. It’s something I haven’t had a chance to get into before. Now I know the basics, which rounds off the DITA picture for me. Thank you Dave for an entertaining and information-packed talk.

Update on DITA Features, Tools and Best Practices

AODC day 2: A Beginner’s Introduction to DITA

This week I’m at AODC 2010, the Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. In this session, though, we’re dealing with wolves, not crocodiles. ;) This post is my summary of one of the sessions at the conference. The post is derived from my notes taken during the presentation. All the credit goes to Suchi Govindarajan, the presenter. All the mistakes and omissions are my own.

AODC day 2: Who's Afraid of the DITA Wolf?

AODC day 2: Who's Afraid of the DITA Wolf?

Suchi Govindarajan had a catchy title for her talk: “Who’s Afraid of the DITA Wolf?”

At the beginning of the session, Tony Self handed out some pretty coloured squares of paper to each of us. Intriguing! The coloured paper was soon explained. Suchi started by telling us a story about origami. Of course, this set me wondering what this origami had to do with DITA! Good start.

Suchi said that she found it really amusing that she was here talking about DITA. About a year ago, she was totally baffled about DITA. Then she attended a course given by Tony Self. Now she’s here to give a beginner’s view of DITA.

She led us through the steps to make an origami pelican, following the step-by-step instructions in her slide show. I’m hopeless at things like origami, but nevertheless I managed to follow the steps (with help from my neighbour) and make something resembling a bird.

AODC day 2: Who's Afraid of the DITA Wolf?

AODC day 2: Who's Afraid of the DITA Wolf?

Next, Suchi showed us some text about origami: an explanation of the theory of origami, an investigation of the maths behind origami, and other theoretical scripts about origami. She explained how different texts have different purposes, and not all are step by step guides, and not all are useful to a beginner.

DITA introductory material

What did Suchi’s origami demonstration have to do with DITA? She showed us some introductory material to DITA, pointing out how the texts were full of words and terms that a beginner would not understand.

So Suchi has written her own definition of DITA, specifically for beginners:

DITA is a standard for technical documents that’s designed to be used with XML. It comes with some free publishing tools.

We already know DITA

As technical writers, we already know much about DITA. Suchi showed us how a number of the concerns DITA addresses, and many of the terms used, have been part of standard technical writing for years. Examples are content re-use, topic-based authoring and content models.

DITA has an elegant way of handling these standard technical writing concepts.

How to learn DITA

Before you start, you need only a very little:

  • An understanding of XML elements and attributes — just know what they are.
  • An idea of the three DITA topic types: concept, task and reference.

Then get a DITA editor, such as XMLMind or XMetal. Suchi usees and recommends XMLMind. You can download a free edition for personal use.

From that point on, the editor helps you to learn the quirks of DITA. Suchi gave us a quick demo of XMLMind, showing us how the editor enforces the DITA rules while you are writing your content.

At this point, you don’t need to know about the complex features of DITA like specialisation, customisation, inheritance, etc. You also don’t need to know about the DITA “topic” topic.

You also don’t need to know about XML rules, validation and well-formedness. The editor will take care of that. You can learn about it later, once you’ve got through the beginner stage.

Because DITA tags are semantic, it’s easy to guess what each element means judging by its name.

Start with a good example. Download and analyse some sample topics. Suchi gave us a link to the DITA OT user guide as a good set of sample topics.

She also recommends this tutorial: DITA for Solo Writers, the Lone-DITA guide.

The real wolves of DITA

DITA is not a wolf, says Suchi. :) On the other hand, the DITA OpenToolkit is horrible. Don’t use it!

Another wolf is ourselves. If you start with a closed mind, it’s hard to learn what DITA offers.

Going further

Once you’ve done some editing and created some content, you can start looking at publishing your DITA content. Here’s where you would install the DITA OpenToolkit, but don’t use it. Instead, install one of the other tools that use the toolkit:

  • WinANT
  • XMLMind DITA Converter
  • Other publishing tools you already own

My conclusion

Thank you to Suchi for a calm, reassuring introduction to DITA. Suchi had the audience in the palm of her hand. Her speaking style is relaxed and charming. She told us about a one-day DITA workshop called “DITA in a Day”, that she has created. It sounds well worth attending!

Follow

Get every new post delivered to your Inbox.

Join 1,494 other followers

%d bloggers like this: