Search icon Looking for something?

December 02, 2016
Print Comments
Our scholarship winners share their experiences with the DITA Workshop held October 2016

Recapping the Basic Workshop - Kelly McMillan

Generic Image
Kelly McMillan
A career change is a major hurdle - new skills are hard to come by if they don’t translate from your previous field. Which was why, after leaving medicine to pursue writing, I was excited for the opportunity to attend the STC-Carolina Beginner’s DITA Workshop.

I had not encountered DITA in my medical career, but it was a skill that I came across during the job search. My knowledge of XML formatting was limited to blogging with CSS, and I wasn’t prepared to spend $1,000+ for a training course that might go over my head.

I was happy to find that I had no problem keeping pace with the STC course. Larry Kunz is an experienced instructor from Duke University, who teaches DITA with a nice balance of concept and application.

The name DITA - Darwin Information Typing Architecture - makes a nod to evolution, based on a process in which ‘child’ elements inherent the characteristics of ‘parents’. DITA adapts to the needs of the particular industry. A specialized Information Architect (IA) defines the ‘look’ of the published document, which allows writers to focus on content, and not get trapped in a time-sink of formatting output. The business benefits of this are obvious - efficiency, consistency, and flexibility.

In essence, DITA allows for the separation of content from how it is presented. Information is divided into topics according to its purpose. Is the reader being asked to perform a task? Learn a concept? Seek a reference for more information? The class went over the common elements and attributes for each of these topic types (tasks, concepts, or reference), and wrote a few practice lines of each. We also covered semantics - elements attached to a certain kind of meaning. If the published style changes, tagged elements are easily transformed.

Throughout the course, we applied these skills while writing a sample document in oXygenXML. Larry's instructions were easy to follow and provided us with a sense of what working with DITA feels like. We dabbled into some advanced concepts, including DITA mapping and metadata, which are covered further in the advanced session.

The Beginner’s Workshop was an excellent introduction to DITA, and I left feeling prepared to take on more advanced courses. It also offered valuable advice for any technical writer - information is only useful if it can be easily read and applied by the target audience. In other words, content is no longer king. With DITA, writers can be assured that their work is presented in a manner that places priority where it should be - on the audience.

Recapping the Advanced Workshop - Richard Devecchis

Generic Image
Richard Devecchis
The Advanced DITA Workshop covered many advanced topics for the implementation of DITA), an XML data model for authoring and publishing. The workshop included both lectures and hands-on experience use the oXygen XML Editor.

Larry emphasized that DITA is a type of structured authoring that allows writers to reuse content across multiple publications formats. Topics covered included cross-referencing, filtering, strategies for content reuse, metadata, adding artwork and tables, DITA Open Toolkit, and troubleshooting common problems such as bad links and references.

I’ll discuss briefly my takeaways for the workshop:
  • Cross-referencing: Cross-referencing allows you to create links to content either within a topic (i.e., a table or steps) or to an external topic. It’s important to prevent the breaking of links by placing them in a relationship table and to make sure they link back so you don’t leave your reader stranded.
  • Filtering: Filtering allows you to customize and reuse your topics by identifying unique information for specific contexts and audiences. It’s a type of metadata for determining what to include, exclude, or highlight (flag). It’s very important to document your filtering strategy, use semantically correct attributes, and use comments to identify elements that are filtered.
  • Content reuse: DITA uses keys for content reuse by establishing a context in which your content can be used. Best practices include using the right element tags, assigning an ID to everything, and avoiding unnecessary details that limit the content to one context.
  • Metadata: Metadata allows you adapt your content for specific contexts. It tells systems what to do with your data and is vital to data being found, managed, analyzed, and consumed. DITA defines a few metadata elements and allows you to define your own using a taxonomy. It’s important that your taxonomy is broad enough to encompass all the categories you want but flexible enough to accommodate change.
  • Artwork and tables: Images and artwork can be inserted into topics and there are various options to regulate size and positioning. There are also a variety of features and operations are available for creating and editing tables.
  • DITA Open Toolkit: This toolkit allows you to use style sheets for HTML and other outputs for web pages which enable you to create a custom look and feel for your content including color, font, highlighting, positioning on page, etc. XSL transforms such as PDF and XHTML (defaults) are available to customize your output format.
  • Troubleshooting: Finally, we covered common errors that occur concerning broken links, references, keys, images, and tables. One important tip was to use oXygen’s “text mode” to help you spot problems with references and tables directly in the XML code.
Overall the workshop was an excellent introduction to the advanced capabilities of DITA and its practical application in the daily life of a technical writer!

More articles like this...
Comments powered by Disqus.