Blog Archives

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!

AODC day 1: An Update on DITA Features, Tools and Best Practices

This week I’m at AODC 2010: The Australasian Online Documentation and Content conference. We’re in Darwin, in the “top end” of Australia. Crocs and docs, what more can you ask for! 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 Tony Self, the presenter. All the mistakes and omissions are my own.

After a busy, informative and fun-filled morning on Wednesday, we broke for lunch. Then Tony Self presented the first afternoon session, called “An Update on DITA Features, Tools, and Best Practices”.

Here’s a photo of Tony. I took it on Thursday morning when he was presenting another session. (I thought I’d better mention that, because he’s sure to notice that he’s wearing his Thursday shirt!)

AODC day 1: An Update on DITA

AODC day 1: An Update on DITA

Tony’s talk covered these topics:

  • An overview of DITA: authoring, content management, publishing tools and the DITA Open Toolkit.
  • A preview of the features in DITA 1.2.
  • The usefulness of specialisation and constraints.
  • DITA as used in various help-authoring tools (affectionately known as HATs).
  • Delivery options for content authored in DITA.

Introduction to DITA

Here are my key takeaways from this part of Tony’s session:

  • DITA is an OASIS standard for a form of XML.
  • DITA is a semantic markup language. There are no presentational elements. This enforces the separation of content from form.
  • When working with DITA, you use a suite of tools rather than a single tool. So for example, you may use an authoring tool for DITA, a separate publishing tool for DITA, another tool for reviewing content, and so on.

Some examples of authoring tools:

  • Arbortext
  • FrameMaker
  • XMetal
  • XXE (XMLmind XML Editor)
  • Serna
  • DITA Storm
  • oXygen

Interestingly, the DITA Open Toolkit is not on the list. The toolkit does not offer an authoring tool.

A hint: Because DITA is a standard, you can use the authoring tools interchangeably. The content is stored in exactly the same format.

Some CMSes are DITA aware:

  • Xdocs can use XMetal, XXE or oXygen
  • DITAworks
  • Ixiasoft DITA CMS
  • SDL Trisoft
  • Vasont
  • Siberlogic Sibersafe

Author-it is not on the list, because it can’t manage DITA content.

Other DITA tools:

  • XMetal Reviewer (an addon to XMetal)
  • Leximation DITA-FMx (a FrameMaker plugin)
  • Content Mapper for Information Mapping

Publishing or rendering tools:

  • MadCap Flare (Flare is not an authoring tool. You can import your DITA content into Flare and then output it into another format such as HTML.)
  • RoboHelp (As above, RoboHelp is not an authoring tool.)
  • Antenna House
  • XMLmind DITA Converter (ditac)
  • DITA Open Toolkit
  • WebWorks ePublisher
  • WinANT Echidna (Tony created this tool.)
  • Arbortext Publishing Engine

Pricing varies considerably. Some tools are free and opensource. Others are commercial and quite expensive.

DITA working with help authoring tools

These are some of the points Tony covered around DITA and HATs:

  • None of the common authoring tools are DITA editors.
  • Some are good DITA publishing tools (in particular, Tony mentioned Flare an RoboHelp).
  • WebWorks ePublisher supports DITA content.
  • Author-it allows you to export your content into DITA format. Note that it exports generic DITA content, not the full semantic markup.
  • With RoboHelp 8, you can import DITA content.
  • Flare 5 supports the import and export of DITA content. It does not support a round trip.

Delivering DITA content

DITA Open Toolkit can convert DITA to:

  • HTML (XHTML)
  • HTML Help (CHM files)
  • Eclipse Help — Tony gave us a quick demo of an Eclipse Help help system. He was running an Eclipse standalone web server from his own machine.

Commercial tools can convert DITA to WebHelp, AIR Help, ePub (eBook format) and many others.

There also plugins for the DITA Open Toolkit, dubbed OT plugins, that can produce:

  • Simple WebHelp
  • Context-sensitive help (Eclipse Help and CHM i.e. HTML Help)
  • AIR Help
  • eBook content

Increasing demand for different help formats

Tony pointed out that more and more user assistance is being delivered on “unusual” media such as phones, tablets, GPS displays, eBooks and augmented reality goggles. One of the beauties of DITA is that the separation of content from representation makes it easier to support a multitude of output media.

Tony’s verdict: Is DITA ready for us to produce professional online help?

If you’re looking for tri-pane help output such as HTML, HTML Help and Eclipse Help, you can do that with the OT.

If you want professional-looking output, you can do that with some work on the CSS style sheets

If you need context sensitivity, you can do that too with a bit of extra work.

But DITA is not quite ready for more sophisticated features such as popups and dropdowns.

DITA 1.2

In this part of the talk, Tony went into the new features of DITA 1.2. I didn’t take detailed notes here. Tony has a lot of information and I’m sure he’d be delighted to pass it on.

One of the bits I found interesting was that there’s been some criticism of DITA 1.2. Some people say DITA is becoming more and more flexible (“sloppy”) and therefore less and less useful, in that you can now add new types of <div> to the DITA “task” topic type. When you upgrade to DITA 1.2, your task topics will automatically become “sloppy”. If you like, you can “constrain” them to make them more strict.

Also pretty cool in DITA 1.2: The new “subjectScheme” ditamap element supports facets, a concept discussed in Matthew Ellison’s earlier session on search. (I’ve blogged about Matthew’s session.)

The DITA 1.2 standard has not yet been officially released. Even so, some tools support it already:

  • Open Toolkit 1.5
  • oXygen

Choosing a tool

Tony gave us some points to consider when choosing a DITA authoring tool:

  • The tool should be as compliant as possible i.e. it should support the current DITA standard.
  • The tool should support the round trip, so that you can open DITA content, work on it and then save it as DITA.
  • You need a tool that supports specialisation, so that you can add your own topic types.
  • It’s good to have a tool that is as open as possible, so that it is extensible and interoperable.

My conclusion

Thank you Tony for a useful update on the current state of affairs in DITA world. In particular, Tony has given us some great information on the tools available. For me, as someone who does not use DITA but is interested in the technology and its aims, it’s really useful to get a quick blast of information in this way.

Follow

Get every new post delivered to your Inbox.

Join 1,454 other followers

%d bloggers like this: