DCL/Authoring Standards-Based Intelligent Content the Easy Way with Lightweight DITA

Authoring Standards-Based Intelligent Content the Easy Way with Lightweight DITA

By Carlos Evia and Michael Priestley, with research assistance and creative input from Virginia Tech undergraduate students Kaitlyn Heath and Caroline Stewart.

On March 27, 2018 Carlos Evia and Michael Priestley presented the webinar “Authoring Standards-Based Intelligent Content the Easy Way with Lightweight DITA.” After the presentation, there was a question and answer period where the below questions were asked.

Based on the committee note “Lightweight DITA: An Introduction,” of the three flavors of LwDITA, MDITA sort of seems to be the "runt of the litter." It looks suitable for creating a new topic, but if the topic is then edited as XML or HTML5, the topic might not then have a lossless transformation back into a Markdown editor. Is this likely to be how it works out in the long term? Will MDITA remain less expressive than XDITA and HDITA – handicapped by its being a version of Markdown? Or do you have some ideas for making MDITA as expressive as the other flavors?

Markdown has serious limitations when it comes to advanced structuring. But let's be honest, there are thousands of communities of developers, technical writers, marketing writers that use Markdown, and they don't even touch HTML5… and forget about XML! MDITA, in its extended profile, can achieve DITA-like content structure and processing capabilities because of HTML5 snippets. This syntax is allowed in GitHub-Flavored Markdown (GFM), and that is the version of Markdown that the Lightweight DITA subcommittee at OASIS decided to (mainly) align with. We understand that there are some MDITA features that will not go back to all flavors of Markdown, but that is true even now if you're writing between, for example, kramdown and Pandoc, or other Markdown flavor. Some extended markup that you can add for expressing attributes will not translate to all of the other versions of Markdown.

MDITA has existed in draft form for a couple of years now in experiments that Michael, other members of the LwDITA subcommittee, and I have been conducting. In those experiments (at the DITA CMS North America conference this month, we saw preliminary reports from Scott Hudson at Jeppesen and Stan Doherty at Oracle), MDITA has satisfied the needs of some authoring communities. Undeniably, it also has some limitations, but MDITA actually gets a lot of attention from the subcommittee, so it's not like the child that we don't love. It really is one of the main selling points of LwDITA, but of course it comes with its limitations.

In this core profile, MDITA will be more “tolerant” of different Markdown notations and will provide an easier roundtrip to a Markdown source environment after joining a LwDITA repository. As mentioned in the question, the committee note “Lightweight DITA: An Introduction” (http://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.html) includes more details about the MDITA profiles.

Will enterprise solutions like Microsoft Internet Information Services render HDITA correctly if it references DITA content, or will it require another step to publish it to regular HTML5?

It probably will not work natively. Like any other extension running on top of standard HTML5, HDITA will need a translating layer to process the content + code before it is delivered to users. In most web content management systems, there will be an element of dynamic scripting or programming behind the scenes to combine HDITA topics with elements referenced from external topics in DITA or another LwDITA flavor.

Do authors of LwDITA need to use a special editor, or do they need to use an XML editor? Engineers we work with like using Word and some would even use Notepad+, but I'm afraid that they would create invalid LwDITA if they don't use an intelligent editor.

The Lightweight DITA subcommittee at OASIS maintains a wiki page (https://wiki.oasis-open.org/dita/LightweightDITASubcommittee/lwditatools) that lists open source and commercial editors and processors that have implemented aspects of the proposed LwDITA standard. We hope that, as developers and users start experimenting with LwDITA, the list of LwDITA-aware tools will grow. In an ideal situation, users will use their existing tools… tools that they use today for creating content in HTML or Markdown, to author topics in HDITA and MDITA. The authoring tasks related to LwDITA should not come with a huge tax of new features for content contributors.

When will LwDITA become available?

The committee note “Lightweight DITA: An Introduction” (http://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.html) is officially out now. It contains enough information to get users, managers, and developers interested in experimenting with LwDITA. The full technical specification for the proposed standard will probably be released in 2019. However, there are tools already implementing some LwDITA features, and the wiki page of LwDITA-aware tools keeps growing.

Is there any talk from the tools community about providing plugins for conversion of LwDITA content to a more robust version of the spec (or vice versa) should a DITA adopter want to convert content?

Interested developers should keep an eye on the wiki page of LwDITA-aware tools maintained by the Lightweight DITA subcommittee (https://wiki.oasis-open.org/dita/LightweightDITASubcommittee/lwditatools) and contribute with processing, editing, and migrating tools. However, before thinking about migration or conversion from LwDITA to full DITA, authors and information architects should look at the compatibility that LwDITA allows: XDITA topics are simpler but valid DITA topics. HDITA and MDITA extended profile topics can share content resources with DITA topics. We argue that in many cases these sharing capabilities will be enough and will not require conversion.

How do you reuse content stored in another format (like XML) into your HDITA web view? what does that look like? Does it require transformation before it can be reused?

It would require a transformation for reuse, in a process similar to the content reuse capabilities of DITA XML. The syntax is pretty similar to reuse functions in DITA: @conref for block-level content, and @keyref for inline content. This is enabled by HTML5 custom data attributes, which allowed us to create reuse mechanisms without XML tags.

Whereas in DITA or XDITA (based on XML) a content reference (conref) is expressed, for example, as <p conref=“topic1.dita#topic-id/topic-segment” />, in HDITA (based on HTML5), a similar reuse structure would be <p data-conref=“topic1.dita#topic-id/topic-segment”>.

How does LwDITA handle Variables, Terminology and large indexes of Conrefs....?

The LwDITA authoring formats were designed to implement those concepts as similar to the DITA standard as possible. However, there are some limitations mainly in MDITA. For users that need large indexes of conrefs, LwDITA might be too lightweight, and they would be better off with full DITA XML, which is not going away as a standard for structuring and publishing content. Keep in mind that the LwDITA authoring formats are compatible with DITA, so if an author starts in XDITA, HDITA, or MDITA and realizes that she has hit a wall in requirements for variables and reuse, she can create another topic or create a map in DITA 1.3, and most of the content created in LwDITA is still going to be compatible with it.