Re: [dita] Replying to Leigh: Summary of Leigh White's comments on the Lightweight DITA Committee Note

["Michael Priestley" <mpriestl@ca.ibm.com>]

Hi Kris, Leigh,

I think there may be no practical difference
for an XML toolchain between saying "HDITA is just HTML5 authored
for interchange with LwDITA" and "HDITA is LwDITA". And
I can see how, if you are dealing only with an XML toolchain, you would
prefer the first statement as being clearer.

But there is a big practical difference
between the two statements for an HTML toolchain.

If the only purpose of authoring in
MDITA or HDITA is interchange with XDITA (the XML flavour of LwDITA), then
all LwDITA toolchains must be XML tool chains.

Given that one of the adoption challenges
LwDITA is meant to address is the aversion that some authoring and development
communities have to XML, I believe we need to keep saying that HDITA is
truly LwDITA, as much as XDITA is.

If a group is using a pure HDITA implementation
with no trace of XDITA, they are still using LwDITA, and can interchange
with other LwDITA groups, and integrate content publishing workflows across
multiple content platforms.

Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com



From:      
 Kristen James Eberlein
<kris@eberleinconsulting.com>
To:      
 dita@lists.oasis-open.org
Date:      
 06/19/2017 12:49 PM
Subject:    
   [dita] Replying
to Leigh: Summary of Leigh White's comments on the Lightweight DITA Committee
Note
Sent by:    
   <dita@lists.oasis-open.org>

---

Leigh, many thanks for taking the time to provide your
review.

I did want to quickly address one area where I think you are making a large cognitive mistake ...

You commented ""XDITA is really XHTML authored with an eye to interchange with LwDITA". It absolutely is not. XDITA is a lightweight version of DITA 1.3; it is the XML variant of Lightweight DITA, not the XHTML variant of Lightweight DITA.

I do agree, off course, that "HDITA is really HTML5 authored with an eye to interchange with LwDITA. MDITA is really Markdown authored with an eye to interchange with LwDITA."

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)

On 6/19/2017 12:35 PM, Kristen James Eberlein wrote:

Thanks, Leigh. I'm going to provide a list of your comments to make it easier for the team to view them:

3 What is Lightweight DITA? -- Last bullet
LW: Should be a level-2 bullet?

3.2 Support for non-XML formats -- "In its initial release, LwDITA has three authoring formats:"
LW: I realize this is a core explanation of LwDITA but it's troubled me since the beginning. And now that you're asking for my opinion, well... :-)

It's potentially confusing, I think, to say that LWDITA has three formats: XDITA, HDITA, and MDITA. Or to say that "X/H/MDITA is the authoring format of LwDITA that uses XHTML/HTML5/Markdown to structure information." This phrasing risks the misconception that LwDITA has three separate tagsets--one for interchange with XHTML, one for interchange with HTML5, and another for interchange with Markdown. That's not the case, not really.

XDITA is really XHTML authored with an eye to interchange with LwDITA. HDITA is really HTML5 authored with an eye to interchange with LwDITA. MDITA is really Markdown authored with an eye to interchange with LwDITA. They are not variants of LwDITA.

To me, the LwDITA interchange with these other formats is analgous to using Simplified English with an eye to translating to Chinese. It would be misleading, then, to say that "Simplified English is the authoring format of Chinese that makes translation easier" (or vice versa).

This explanation also positions LwDITA as the content creation medium and XHTML/HTML5/Markdown as the targets...implying that you use one the "variants" of LwDITA to create content that will be converted to one of the other formats. While this might be the case, I think it's more common that the process will be reversed--XHTML/HTML5/Markdown will be the authoring medium and LwDITA the conversion target.

It's more accurate and clearer, I think, to say that "X/H/MDITA represents a subset of the XHTML/HTML5/Markdown tagset that facilitates interchange with LwDITA to structure information."

I think it comes down to...do we consider LwDITA to be:

* a specific tagset, i.e. a subset (mostly) of standard DITA that has interoperability with subsets of the XHTML/HTML5/Markdown tagsets (or markers in the case of Markdown)
* specific DITA-based tagset but also the XHTML/HTML5/Markdown tagsets, which although not defined in the LwDITA spec and not explicitly part of the LwDITA tagset, are understood to come under the same "interoperability umbrella," as it were.

The first option is much clearer to explain and easier for folks to wrap their heads around, I think. There is one LwDITA tagset, period. Folks who have been using DITA for some time are accustomed to thinking of it as a solid thing--a certain set of tags. When they are creating DITA content, they see those tags, period. When considering LwDITA, they can easily understand that LwDITA consists of a subset (mostly) of the standard DITA tags. When creating a a LwDITA topic, they expect to see that subset. If they were creating an HTML5 topic, they'd expect to see *that* tagset available to them. If they were creating a Markdown topic, they'd expect to see *those* markers available to them. In their minds, they are creating one thing or another. It's a weird and murky area to explain that, "No, actually LwDITA is all of those things." A natural reaction might be, "Well, then rather than calling LwDITA "Lw*DITA*" when it actually means XHTML and HTML5 and Markdown and DITA, why not come up with a name that covers all four, like "MarkupInterchange" of which LwDITA is one aspect, rather than expecting us to understand that DITA doesn't mean just DITA anymore but a bunch of other stuff, unless you're talking about *standard* DITA, in which case DITA still means just DITA."

But as we seem pretty heavily invested in this explanation/concept, then an upfront explanation (and perhaps a contrast with the first point) would be very helpful.
This point affects numerous places throughout this paper, which I have not specifically marked.

Typo on page 10
Change other --> others

Missing period on page 12

5 LwDITA authoring formats -- Departments who want to reduce the cost of developing and maintaining style sheets
LW: Honestly, while it's worth mentioning, I don't see this as much of a driver. In my experience, groups are (unfortunately) still not especially willing to compromise on output formatting. They are happy to work with a more complex structure (sometimes even adding complexity of their own) if it means their output will be JUST SO. This may change as content becomes less persistent (e.g. daily automated updates)

Page 15
Correct indent in code sample

Page 16 -- "All XDITA topics are designed to be fully compatible with DITA 1.3 topics."
LW: A bit misleading? I think it will be a very common scenario to have LwDITA topics alongside standard DITA topics in a standard ditamap. These multimedia elements are a glitch in that scenario in that they are not present in standard DITA and impede complete compatibility. What is the recommendation? That groups specialize these elements from <object> in their standard DITA DTDs, just as they have been specialized in LwDITA?

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)

On 6/19/2017 11:36 AM, Leigh White wrote:
Hi all,
 
Apologies…posted originally in error to Adoption Committee.
 
Per your request to review the note, which Keith passed along, I’m attaching a commented version of the note that I just read through. The crux of my commentary is in the sticky note on p. 9. I noted a few other minor things and typos as well. Being a bit gun-shy about critiquing committee work, I’d like to stress that I approached this note as if I were a naïve user…how much sense would it make? Would the relationship between LwDITA, XHTML, HTML5, and Markdown be clear? And, as I explain in the note, I don’t think it would. As always, take this as my two cents, to acknowledge or ignore. My continued thanks and gratitude to the committee for all of your hard work!
 
Best,
Leigh
 
Leigh White
DITA Specialist

825, Querbes suite 200 | Montreal, Quebec, Canada, H2V 3X1
toll free: + 1 877 279-4942
leigh.white@ixiasoft.com/ www.ixiasoft.com
 

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php