Do you need to write your content in collaboration with developers, marketers, and other teams that don’t know DITA? Or maybe your team is being pressured to deliver content minimum viable products (MVPs) quicker and more flexibly. In today’s world of agile software development and GitHub as source-controlled content management system (CMS), you might wonder if DITA, which began development way back in the last millennium (begun by IBM in 1999, donated to OASIS in 2004), is too “heavy” for modern build pipelines and agile processes. Enter lightweight DITA (LwDITA).

Alan Houser, former STC President and co-founder & president of the Group Wellesley, Inc. technical writing consultancy, introduced STC Carolina to lightweight DITA in our monthly professional development series on February 28, 2019. LwDITA is a simplified version of DITA that comes in different flavors to accommodate diverse authoring formats while still preserving key structured authoring principles for modern content publication.

What’s changed and what’s stayed the same in LwDITA?

LwDITA is curated to keep the most useful features of DITA to support rapid content development, agile delivery, and cross-departmental collaboration. In particular, LwDITA is still topic-based, supports content aggregation via DITA maps, and keeps key DITA functionality for filtering, conrefs, and keywords.

Where LwDITA differs from DITA is in the volume and specialization of its features. As its name implies, LwDITA has stripped down many of DITA’s 600+ specialized tag elements and 12 content types. LwDITA features only 2 content types: topic and map. It drops more advanced features that are not as commonly used, such as topic types, inline domains, reltables, topic groups (sequence, choice), bookmaps, branch filtering, automated output chunking, scoped keys, and subject scheme mapping.

It’s important to keep in mind that LwDITA is not a substitute for DITA. Depending on your business requirements and industry, DITA is still the preferred way to deliver technical information for content management, topic reuse, and multichannel publication. LwDITA focuses on cross-format support so that you can use it in conjunction with other authoring languages, specifically Markdown and HTML.

How does cross-format LwDITA work?

LwDITA supports three authoring formats: XDITA (simplified DITA), HDITA (HTML with DITA), and MDITA (Markdown with DITA). Your LwDITA publishing solution might incorporate all three, such as technical writers continuing to write mostly in XDITA, docs that are co-owned with development teams in Github using MDITA, and marketing products for websites being written in HDITA. You can write both content types, topic and map, in each format.

XDITA

For those familiar with DITA, XDITA will feel like an old friend. The following example from the OASIS standard is for a LwDITA topic, and includes a new tag, video.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD LIGHTWEIGHT DITA Topic//EN" "lw-topic.dtd">
<topic id="install-and-setup">
  <title>Installing and Setting up Remote Lighting</title>
  <shortdesc>Installation of your lighting kit includes installing the light bulbs into 
  light fixtures, preparing the remote control, and programming lighting groups.
  </shortdesc>
  <prolog>
    <data name="author" value="Kevin Lewis"/>
  </prolog>
  <body>
    <section>
      <title>Steps</title>
      <ul>
        <li><p>Install light bulbs.</p></li>
        <li><p>Prepare remote control.</p></li>
        <li><p>Program lighting groups.</p></li>
      </ul>
    </section> 
    <section>
      <title>Example</title>
      <p>The following video demonstrates a recommended installation:</p>
      <video>
        <video-poster value="remote-poster.jpg" />
        <media-controls />
        <media-source value="remote.mp4" />
      </video>
    </section>
  </body>
</topic>

HDITA

If you contribute regularly to your product’s graphical user interface (GUI) or website, you might also be familiar with HTML. The following example from the OASIS standard will look very similar.

<!DOCTYPE html>
<html>
<head>
  <title>Installing and Setting up Remote Lighting</title>
</head>
<body>
  <article id="install-and-setup">
    <h1>Installing and Setting up Remote Lighting</h1>
    <p>Installation of your lighting kit includes installing the light bulbs into 
    light fixtures, preparing the remote control, and programming lighting groups.</p>
    <h2>Steps</h2>
    <ul>
      <li>
        <p>Install light bulbs.</p>
      </li>
      <li>
        <p>Prepare remote control.</p>
      </li>
      <li>
        <p>Program lighting groups.</p>
      </li>
    </ul>
    <section>
    <h2>Example</h2>
    <p>The following video demonstrates a recommended installation:</p>
    <video src="remote.mp4" controls poster="remote.png"></video>
    <p data-conref="bulbs-to-groups.dita#bulbs-to-groups/assign-disclaimer"></p>
    </section>
  </article>
</body>
</html>

MDITA

Software doc writers are probably familiar with GitHub’s Markdown implementation, especially with all their products’ READMEs (or lack thereof!). In LwDITA, you can also author in Markdown, such as the following map from the OASIS standard. You could also add some tag elements into the Markdown, such as to support translation processes by adding <span translate=”no”>.

# Remote Lighting Network for <span translate="no">SuperLightingProductName</span>
   - [Introduction](introduction.md)
   - [Alternative lighting setups](alternatives.md)
       - [Low power installation](low-power.md)
       - [High power installation](high-power.md)

Learning more about LwDITA

To learn more, check out the OASIS standard, get involved in the steering committee, or try out some LwDITA tools. Carlos Evia has also written a book, Creating Intelligent Content with Lightweight DITA. He is also scheduled to give a talk about LwDITA at the STC Summit, so register today!

 

Recap contributed by Art Berger. Art is a technical writer for IBM Cloud as well as a blog editor for STC Carolina. Connect with him on LinkedIn or Twitter.