Lightweight DITA: What Is It and Can I Use It in the DITA CMS?

One of the biggest obstacles to DITA adoption is its perceived complexity. As of DITA 1.3, the complete element list has grown to over 600; just the base elements plus the technical content elements total more than 400! That’s a lot of elements for users to learn, although of course, few groups actually use all of them.

Any good XML editor can do considerable “handholding” for a writer to guide him or her through the construction of a topic or map by offering a list of only the elements that are valid in the immediate context. Well-constructed topic and map templates can help a lot too by setting up the initial structure that writers only need to “drop” content into.

Still, the nature of DITA means there can always be some ambiguity as to exactly which valid element to use in a given context. And too many choices can be paralyzing, especially for content creators who are not technical writers and who don’t have the time or the inclination to learn DITA.

To reduce the complexity, many Information Architects have developed a constrained set of elements for their writers to use, using the standard constraint mechanisms made available with DITA 1.2. However, constraints are not trivial to develop or maintain, and probably not feasible for groups without an Information Architect or the funds to contract the constraint development.

Several CMS vendors have recognized this challenge and offered applications that present a limited element set to users (with the option to expand the list as writers’ comfort with DITA increases). However, there has been no standardization among these vendors as to exactly which elements and attributes to offer, nor among the methods used to constrain the element list.

In comes Lightweight DITA, or LwDITA. At its most basic, LwDITA is a separate DITA specification that defines a much smaller element set. At present count, LwDITA includes just 38 elements. This limited element set makes it much easier for writers to start using DITA, as well as simplifying DITA for content contributors who are not primarily writers, such as engineers or support staff.

LwDITA maintains full compatibility with the DITA standard so that interchange of content is smooth. By definition, all LwDITA content is valid in the context of standard DITA, so LwDITA topics and maps can be used alongside standard DITA content with no need to create special transformations or validation.

LwDITA will become part of the official DITA standard, but it did not make it into the recently-published DITA 1.3 specification.

Uses of Lightweight DITA

LwDITA is generally not intended to be an organization-wide permanent replacement for standard DITA. Instead, you might use it as “DITA training wheels” for writers new to DITA. After they have become comfortable with the concept of structured authoring, you can switch them to standard DITA.

SMEs, engineers, or other non-writer content contributors can remain in LwDITA, but the assumption there is that after they author the content, a writer or Information Architect will then incorporate that content into the standard DITA content set. At that point, all of the DITA bells and whistles can be added, such as relationship tables, metadata, additional filtering attributes, and so forth.

For these reasons, LwDITA does not include, or does not fully include, many of the more advanced DITA features. The expectation is simply that people using LwDITA are not at an advanced enough level with DITA or do not have enough knowledge of the content collection to use these features correctly and productively.

That said, there may be organizations whose documentation needs are simple and straightforward enough that LwDITA is a sufficient permanent model for some or all of their content. Or, while DITA content intended for fully-featured online help or user guides might use the standard DITA element set, DITA content intended for wikis, blogs, or knowledge bases might continue to use the LwDITA element set.

Features of Lightweight DITA

DISCLAIMER: The LwDITA specification is not yet finalized. Any of this information is subject to change!

Some notable differences between standard DITA and LwDITA are:

• Mixed content is not allowed. All text must be in a <p> element. For example, <li>This is a list item</li> is not allowed. It must be <li><p>This is a list item</p></li>. This restriction ensures a uniform, predictable structure across content, simplifies reuse, and makes it much easier to develop stylesheets and tools to process the content.
• There are no CALS table elements (<table>, <row>, <entry>, etc.).
• There is no prolog metadata (everything is in <data>).
• There are no related links.
• Only the highlighting domain is available, and only a subset of it (<b>, <i>, <u>, <sup>, <sub>).
• Only topic is available; there is no concept, reference, task, glossentry, etc.
• Only map is available; there is no bookmap.
• Maps do not have a <title> element. The title, if one is necessary, can go in <navtitle> within <topicmeta>.
• Only <topicmeta> and <topicref> are available; there is no <topichead> or <topicgroup>.
• Out of the box, the full set of filtering attributes are not available. Only @props is available. Individual filtering attributes can be added as necessary.
• Overall, attributes are managed as functional groups which can more easily be enabled or removed.
• Specialization is much simpler.

Compatibility between LwDITA content and standard DITA content

As mentioned earlier, LwDITA is a subset of standard DITA, so by definition any LwDITA content is completely compatible with a standard DITA environment. You could create a simulated LwDITA topic in a standard DITA environment simply by using only the elements and attributes available in LwDITA and ignoring the others.

Similarly, it’s possible to use LwDITA topics and standard DITA topics together in a standard map, and to use LwDITA maps and standard DITA maps together in standard maps or bookmaps.

The reverse is not true. You cannot use standard DITA topics and maps in a LwDITA environment because that content might include elements and attributes that are not available in LwDITA.

Can you round-trip between standard DITA and LwDITA? In a word, no. Once a LwDITA topic or map has been made standard, it’s potentially going to contain a lot of elements and attributes that have no clear equivalent in LwDITA. There’s currently no mechanism to map a reduction of the very large set of standard DITA elements and attributes down to the much smaller LwDITA one. Likewise, there’s no predictable mechanism for mapping a single LwDITA element (for example, <ph>) to its many possible equivalents in different contexts. You might be able to develop a mapping that works specifically for you, but it’s highly unlikely to work as well for anyone else, so there is no attempt to standardize this round-tripping.

Where can I get Lightweight DITA?

If you’d like to begin playing with LwDITA outside of the DITA CMS, a preliminary set of DTDs is available on GitHub at https://github.com/oasis-open/dita-lightweight.

Using Lightweight DITA in the DITA CMS

If you’re interested in integrating LwDITA into the DITA CMS and experimenting prior to the official release, contact MadCap IXIA CCMS Support. We can provide you with an integration package that includes the LwDITA DTDs, topic and map templates, and instructions.

At present, there are a few considerations.

Auto-translation. Out of the box, the DITA CMS is set up to add the ixia_locid attribute to elements when you release a topic or map. If it cannot add the attribute, it cannot release the topic or map. This attribute is an IXIA CCMS specialization and not part of the LwDITA specification; therefore, it’s not valid for LwDITA content. If you want to use LwDITA content in the DITA CMS, you must turn off auto-translation for all content, not just LwDITA content, so that the DITA CMS does not attempt to add this attribute.

It is possible to integrate @ixia_locid into LwDITA but at that point, the content is no longer strictly LwDITA content. You are welcome to integrate this attribute yourself (and the IXIA CCMS LwDITA package includes the necessary code) if you need to use auto-translate, but IXIACCMS does not integrate it out of the box.

Map creation. As mentioned earlier, LwDITA maps do not have a <title> element; the title goes in <navtitle> within <topicmeta>. The DITA CMS now offers the option (as of 4.2.33) to use a parameter ({ixia.title}) to specify where the title of a map should be placed, which allows you to create LwDITA map templates that use this parameter in the <navtitle> element.

If you integrate LwDITA into a DITA CMS version earlier than 4.2.33, you cannot create LwDITA maps within the DITA CMS. There are two workaround options:

• Create the basic LwDITA map structure outside of the DITA CMS and import it.
• Create the map in the DITA CMS as a standard ditamap, then edit it to change its structure and doctype.

A note on Markdown in the DITA CMS

Several customers have asked about using Markdown in the DITA CMS. The short answer is that we’re looking into it. It’s not a simple matter. The DITA CMS is designed to accommodate DITA XML content and XHTML content. Markdown is neither. Markdown content does not have the necessary structure that allows the DITA CMS to index it properly.

Our preferred approach is to create an automatic round-trip transformation, whereby users create a topic in Markdown and upon release, the DITA CMS transforms the topic to LwDITA so that that the DITA CMS can correctly index it. When a user locks the topic to edit it, the DITA CMS transforms it to Markdown again.

There is a Markdown transform available, cleverly named DITA OT Markdown and found at https://github.com/jelovirt/dita-ot-markdown/. IXIA CCMS has begun to experiment with this plugin and we’ll keep you posted. Round-tripping from one format to another is always risky and we want to be sure we maintain the content integrity through such a process. We do not have a specific timeline for implementation, so if Markdown is critical for you, please let us know by adding or upvoting an existing feature in the Evolution Lab at http://lab.ixiasoft.com/.

LwDITA at the IXIA CCMS User Conference

A presentation/demonstration of LwDITA integration and possibly Markdown is planned for the IXIA CCMS User Conference, September 28-30 in Montréal. If you’re interested, you can learn more there!

If you’re interested: elements and attributes allowed in Lightweight DITA

Superscripted text lists the attributes available on each element, based on the Attribute groups list at the end of this section.

• topic^{1 (+ id)}
• title¹
• shortdesc¹
• prolog¹
• body¹
• section^{1 2 3}

List elements

• ul^{1 2 3}
• ol^{1 2 3}
• li^{1 2 3}
• dl^{1 2 3}
• dlentry^{1 2 3}
• dt^{1 2 3}
• dd^{1 2 3}

Text elements

• p^{1 2 3}
• pre^{1 2 3 (+ xml:space)}

Table elements

• simpletable^{1 2 3}
• sthead^{1 2 3}
• strow^{1 2 3}
• stentry^{1 2}

Image elements

• fig^{1 4 (+ outputclass)}
• image^{1 5 (+ href, height, width)}
• alt^{1 5}

Media elements

• audio^{2 3}
• video^{2 3}
• param ^{(name, value)}
• desc¹
• poster ^{(name, value)}
• source ^{(name, value)}
• track ^{(name, value)}
• fallback¹
• controls ^(name)

Other elements

• data^{5 (+ name, value)}
• xref^{1 5 7}
• ph^{1 5}

Map elements

• map^{1 (+ id)}
• topicmeta
• topicref^{2 3 6 7 8 (+ locktitle)}
• navtitle¹

Attribute groups

The groups listed here are defined by the LwDITA specification.

¹localization (@dir, @xml:lang, @translate)
²filters (@props)
³reuse (@id, @conref)
⁴fig.attributes (@scale, @frame, @expanse)
⁵variable-content (@keyref)
⁶reference-content (@href, @format, @scope)
⁷variable-links (@keyref)
⁸control-variables (@keys)