OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Aggregated feedback on Lightweight DITA committee note

Dear all,

This is a compilation of the messages I have received with feedback on the LwDITA committee note.



## From Fiona Hanington

Hi there

Markdown is mentioned - what about Restructured Text (rst)? This is quite widely used in the Python developer community. What would it take to include similar support for that markup lang?


## From Chris Despopoulos

Hi Carlos...

I'm flattered that you asked.  And I'm excited to see things coming to light!

Overall I think the document is good.  The structure is clear, and it reads easily.  If anything, then in the Why LwDITA section it might be interesting to spell out some ideal use cases...  Collaboration with engineers, breaking into the Marketing silo, aggregating content to generate XDITA out of a mixed book that you can send to an OEM...  Painting these pictures might be interesting and helpful.

Aside from that, the tech writer in me can't help but give you the following comments:

"LwDITA is intended to be a conforming subset of DITA 1.3. In order to make this possible, the DITA Technical Committee will release a new multimedia domain for use with DITA 1.3." -- I was left wondering why these follow.  It would be good if you clarified that point here.  I guess the point is, in order to really support HDITA you need to support media.  But then that exceeds DITA 1.2, so 1.3 has to add corresponding elements???

"Conference presentations and practitioners' blogs occasionally describe DITA as an intimidating language..." Technically speaking, I don't believe DITA is a language, so much as a grammar.  Anyway, back in the SGML days, a DTD was described as the means to express a grammar expressed in the SGML language.  But maybe that's not how people talk about DITA these days?

"...and 189 element types. In contrast, LwDITA has two document types and 48 elements." In one you refer to "element types" and in the other, just plain "elements."  You should be consistent -- I prefer the latter.

"These authoring formats will enable and enhance collaboration across divisional silos."  This might be true, but what you mean to say is that *implementing DITA* in these formats will enable and enhance.  To be more accurate, you don't KNOW that it will enable and enhance, but you believe it will, and so you support these three implementations of DITA in hopes that they will enable and enhance...

"...can be aggregated together..." This is a repetitious redundancy.  :)

So...  I hope this is helpful, and at the level you're looking for.  I'm excited to see this coming together!!!

## From Tom Johnson

Carlos, I had a chance to check out the LwDITA paper. It looks pretty good to me. Thanks for sharing it. It's interesting to see the different levels of lightweight support, with XML, HTML5, and Markdown. It's also neat to see the GFM flavor of Markdown embraced (instead of Commonmark or kramdown). Overall, I think the lightweight spec will be a significant advancement toward adoption and integration of XML. I'll be interested to see what kind of tool support is developed for the lightweight solutions.

Just curious, but what has been the reception/adoption of the Markdown integration into Oxygen?

Some general feedback I have:

- The dual flavors of Markdown, with an extended profile and a regular version, seemed like too many variations to me. Why not just one Markdown version?
- I like the ability to reference a link through the title. Seems useful.
- I like the ability to specify frontmatter tags in the content.
- I wasn't sure why Markdown definition list formatting isn't supported, though I may have grown accustomed to kramdown Markdown conventions for definition lists. I'm not sure if those same conventions are supported by GFM.
- I was disappointed not to see any conref support for Markdown.

I do like working in Markdown and using static site generators. Part of the appeal is the ability to extend the functionality through custom scripting. In the case of Jekyll, the integration of Liquid offers a lot of possibilities for more advanced content. Right now I'm storing tooltips in a YAML file, embedding them in a doc page, but also rendering them into a JSON output for integration into an app's UI (presumably through _javascript_, though I'm leaving that up to the front-end developer). It's this kind of flexibility that appeals to me about Jekyll (and its complementary utilities with Liquid, and formats like JSON and YAML).

I do recognize that custom scripting is a double-edged sword. The more custom things I do in my tool, the more married I become to it, and if I ever want to switch to another platform, it will become more difficult. The beauty of standards, particularly DITA, is the tool agnosticism. That's partly why I'm curious about the popularity of the Markdown support for Oxygen. I'm guessing that if someone has implemented a doc solution using a static site generator like Jekyll, with custom scripting and so on, it will be difficult for them to simply migrate to Oxygen or some other tool, especially if the other tool doesn't support any of the Liquid scripts or other more advanced code or theme logic the person developed.

For example, if switching systems, I'd need a similar way to store tooltips and render them out into the specific JSON object I've defined. No doubt I could store snippets in XML, but how would I iterate through a YAML list and output the content into a JSON object? That's where I'm not quite sure.

If tool vendors to release themes that have some functionality often missing in static site generators, such as robust sidebar navigation, responsive design, search, commenting and review, and more, particularly support for the OpenAPI spec, then the tools will certainly get traction.


## From Radu Coravu

Hi Carlos,

Thanks for notifying us personally. I skimmed a little through the 
content of the paper. It's great that the paper exists as now we can 
link to it when people ask about what LightWeight DITA is.
A couple of things which are more related to the standard and not to the 

- I think DITA OT 3.0 has default support for Markdown to DITA so it can 
probably also be added to the paper in the tools section.
- Somehow I consider the decision to support both "keyref" and "conref" 
a little bit strange, I understand why but still... it becomes a mix of 
DITA 1.1 and 1.2 functionality.
- I would have liked a specific way to specify the ID on an element in a 
Markdown file or to specify a conref in the Markdown file without 
needing to write HTML elements there.
- Maybe support for those "audio" and "video" elements (which are very 
useful and should have been in the DITA standard) could have been added 
later on, somehow the set of elements in LightWeight DITA could have 
always been a subset of the full DITA standard. But with these 2 
elements added, it's vocabulary is no longer a subset.


Carlos Evia, Ph.D.
Director of Professional and Technical Writing
Associate Professor of Technical Communication
Department of English
Virginia Tech
Blacksburg, VA 24061-0112

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]