Technical writing’s newest trend

How Lightweight DITA might be the future for structured authoring

LwDITA and the future of documentation

According to oasis-open.org, “Lightweight DITA is a standards-based alternative for situations in which DITA 1.3 would be too complex or for communities that do not use XML as an authoring platform” meaning: Lightweight DITA (LwDita) is an alternative solution for a standardized markup language that is easy to learn and easy to use. It seems like a vial be compromise between DITA XML and markdown.

Photo by Jenelle Hayes on Unsplash

The goal of LwDITA is:

• Provide a simpler DITA experience
• Provide mappings between XML, HTML5, and Markdown that enable individuals to:
• Author content in the format of their choice
• Easily exchange and publish content whose source exists in these different markup languages
• Foster the growth of new, low-cost tools and applications that support LwDITA

The intended audience of LwDITA is for teams that have not adopted a standard based solution for documentation. LwDITA is best for teams that are being introduced to structured authoring and content reuse.

While LwDITA supports core features in the DITA standard — semantic tagging, topic orientation, content reuse, conditional processing, and specialization — LwDITA deliberately limits itself to generic structures that are highly applicable across many industries. This results in a much smaller standard in terms of elements, attributes, features, and complexity.

I believe that LwDITA should be adopted by teams who are looking for a compromise between DITA XML and markdown. Where they want to have control over tags and reusable elements but don’t want the complexities of a mature language like DITA 1.3.

It is also useful for software developers who want to contribute to the documentation but don’t have time or the patience to learn all of DITA-based documentation tags.

There are some new tags that LwDITA contains that might help teams decide on a model — these stags include:

• Audio — Audio is a link to sound to be included in the content.
• Autoplay — Autoplay determines if audio or video content should automatically begin to play
• Controls — Controls enable user interfaces for video playback and volume in Web-aimed transformations.
• Loop — Loop automatically returns to the start of audio or video content upon reaching its end.
• Muted — Muted indicates if the audio of a media object will be silenced or not.
• Poster — Poster is a link to an image or static video frame.
• Source — Source is a link to media resources of audio or video content.
• Track — Track is a link to time-based text data relevant to audio or video content.
• Video — Video is a link to an audiovisual product to be included in the content.

These new tags are great as it allows the writer more control over the documentation without having to learn HTML. The writer can use their skills to have more control over how the documentation is presented.

LwDITA is an interesting alternative to some of the modern structured authoring languages like AsciiDocs. One point I would counter with LwDITA is that it is “lightweight”. Meaning that if you have a robust or complex scenarios then you should think of these use cases before jumping to LwDITA. LwDITA’s purpose it to maintain its lightweight nature so specialization should be avoided.

If you would like to learn more about LwDITA consider reading the documentation here.