AODC – DITA workshop

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. This morning Tony Self hosted a workshop entitled “Introduction to DITA”. I learned a lot, about the DITA schema itself and especially about its application and the team and management structures you might need if you’re planning a large documentation project using structured authoring.

Tony is a founding partner of HyperWrite. He has a wide experience in technical documentation projects and is a skilled and engaging presenter.

A point of interest: Much of the HyperWrite web site is maintained in DITA and is transformed to XHTML when rendering the web page.

This was an excellent session, and there’s far too much content to cover in a blog post. Here are some highlights from Tony’s lecture and the discussions within the class.

Introductory points

These are items Tony discussed before we dived into DITA itself.

  • A stated aim of XML is that all human knowledge should be stored in XML. Wow, I hadn’t heard that before. That beats the theory of everything!
  • We compared DITA with DocBook. DocBook was developed by O’Reilly as a means of making their publishing process more efficient. It’s now an open standard maintained by OASIS. DITA was originated by IBM, but is now also maintained by OASIS.
  • DITA is topic-based. A book, or other publication, is a “collection” of topics. DITA is usually thought to be better for procedures, help systems, and other types of documentation with can be broken down into chunks.
  • DocBook is document-based — you might write an entire book in one single file. It’s generally thought to be better for books etc.

Structured authoring

Structured authoring is a whole new way of writing. It requires new procedures, new team structures and new ways of thinking about content. The advantages you gain are things like:

  • Content re-usability (one chunk of information can be pulled into multiple different documents)
  • Single sourcing (documentation stored in one place and format; can be published to multiple formats)
  • Separation of content from presentation

DITA is designed specifically for structured authoring.

A question arose: How can writers make sure that the content they write will fit into the context in which it is used? Tony agreed that this is a concern, and one that is often discussed. In practice, the writer will often be given some context. He says that this concern is probably not as much of a problem as it appears up front.

This discussion brought to mind a web site I saw a few weeks ago, which allows DITA authors to load their documents (i.e. topic collections) onto a platform where others can review the output in its final form. The web site is supplied as a SAAS application. I can’t remember the site URL, and Googling it hasn’t helped. Does anyone know of this site?

DITA itself

Now we dived into the details of content re-use; repurposing via transformations; inclusion/exclusion of conditional text and the creation of a content model.

A question arose: Talking about the content model and the DITA schema, what do you do if the DITA schema does not contain the elements you need for your particular application? In this case, the example was taken from the RADAR equipment industry. Interestingly enough, a committee is currently sitting to design a new content model for the machine industry, which may contain the sort of “warning” elements required by the questioner.

In the wider context, DITA architecture is designed to encourage “specialisation”. You create your own elements to suit your needs. When you need to share your content model with others, DITA supports a process called “generalisation” to make this possible too. The core concepts of “evolution”, “specialisation” and “generalisation” are implicit in the name “Darwin Information Typing Architecture” or DITA.

We did some work on the basic elements of the DITA schema. A point of interest: One of the attendees noticed that many of the DITA elements are similar to the Dublin Core. Tony said that this is by design, for easy interchange.

The big debate around stem sentencesđŸ˜‰

DITA does not allow stem sentences! (Oh dear, the things that technical writers worry about.)

A stem sentence is the short introduction that you might put at the top of a bulleted list, for example. Like this:

To wash the dishes:

  1. Put the plug in the plug hole.
  2. Turn on the tap.
  3. …etc…

In DITA, there’s no legitimate way to add the above phrase “To wash the dishes”. This has led to fiery debate in the documentation community. No doubt it will continue to do so. You could cheat and add the phrase into a <p> element within the <context> element that DITA does allow before the <steps> in a <task>. But this has problems:

  • The stem sentence will not be included in the list of <steps>, if you use the <steps> as a unit outside the <task>.
  • The stem sentence will be an ugly orphan at the end of <context> if you use <context> as a unit outside the <task>.
  • The stem sentence probably duplicates the <title> anyway.

Oh dear oh dear.

So what do you think — are stem sentences a Good Thing or a Bad Thing?

The future

Tony asked what reading formats we might be using in 2010, for example. He mentioned Sony’s BBeB (BroadBand electronic Books). Now all we need is a transformation from DITA to BBeB.

A fun simulation

Try this out: http://www.structuredauthoring.com/simulation

First, do the “Interactive Puzzle” in Part 1. Follow the instructions in the left-hand panel. You will remove all formatting from a web page, bit by bit. Now you can see how difficult the information is to assimilate when the presentation layer has been removed and there’s no semantic tagging. Then Part 2 lets you practise some structured authoring.

A DITA project team

These are the people who might be involved in a large DITA documentation project: the schema designer (if you need to add specialisations to the standard DITA schema); the information architect (creates the ditamap i.e. the structure of the documentation); information developers (these are the content authors); a publisher (defines the data transformation).

Tony pointed out that this specialisation of roles will actually take us back a few years, to before the desk-top publishing era. With DTP, most technical writers create the content, presentation, graphics, and so on. With structured authoring, the information developers are concerned only with the content.

The complexity in designing a topic-based documentation system

If your documentation base is very large, it’s a time-consuming and complex task to design and allocate the topics. Each topic may be re-used in multiple documents, and the topics are written by multiple authors. This needs very careful coordination and management.

Tools

Tony mentioned a number of tools for DITA and other structured authoring, including these:

  • XMetaL — authoring environment; an example of a DITA editing tool; includes a map editor (used to build your structure i.e. table of contents)
  • Task Modeler from IBM — for design of the maps
  • WebWorks — for defining the structure and publishing the DITA topics
  • Antenna House — converts ditamaps into PDF
  • Author-it — structured authoring; single sourcing; a mature product. But note that its DITA support is output only — you can output DITA but you can’t edit it within AuthorIT.

Tony has also developed his own publishing tool, using the DITA Open Toolkit. This tool handles the publication side of things, not the authoring or structuring. He is interested in any feedback you may have.

My conclusions

Thank you Tony for a very interesting session. I can certainly see the benefits of DITA as a storage format. The one thing I haven’t yet come across is that killer WYSIWYG editing front-end. With any luck, I might hear more about that in the next few days at the conference.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 13 May 2008, in AODC, open standards, technical writing, xml and tagged , , , , , , , . Bookmark the permalink. 6 Comments.

  1. Margaret Hassall

    Hi Sarah,

    I’ll be at the conference as well – hope to catch up with you.

  2. Epic Editor is another editor that can be used for editing DITA. It offers a somewhat wysiwyg editor in that the tags are represented graphically.

    I do not feel that stem sentences are necessary if you write the content of your in the right way.

  3. The DITA workshop can learn something there. however nice to read a greats articles.

  4. One other way to implement a ‘push-button’ is to have a publishing system that encapsulate a content management system. The system manages version of documents, authored and stored according to XML document type definition. And roles who work on the system has designated workflows and procedures. The content can be output into various media, ie print and online, by applying the respective stylesheets like CSS, PDF etc. This concept has been used by one of the largest multi-national legal publisher for years.

  5. Hallo Julianna,
    That’s an excellent point. The interaction between DITA and a CMS, along with the roles of the content developers, designers and others is a fascinating topic, especially for those like me who have read about it in theory but not yet been able to put it into practise. There’s a good write-up in this paper. You’ve mentioned the large multi-national legal publisher in a couple of comments. Would you be able to point us to a public documentation site we can take a look at?

  6. Thanks for the link to the write-up, ffeathers. Interesting read, all concepts applicable. Unfortunately the company I used to work for, do not publish public documentation; mainly documentation and white papers for internal use across the globe as they have offices in Europe, UK, US, and Asia Pacific.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: