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

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


From:      
 Kristen James Eberlein
<>
To:      
 
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:    
   <>

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
/ 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