OASIS Darwin Information Typing Architecture (DITA) TC

Document Name : Lightweight DITA: An Introduction Description Marked version with changes implemented after public review #1. Thanks to Alan Houser for the transform. Download Latest Revision Public Download Link Submitter : Dr. Carlos Evia Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2018-01-18 10:20:42

The subtitle should be Committee Note 01 The date needs to be the date on which the TC will vote on the committee note: 23 January 2018 The file name should be LwDITA-v1.0-cn01 . (The easiest way to handle this is to rename the DITA map.) In Specification URIs : The content currently in This version should move to Previous version . The URLs for This version need to be as follows (changes indicated in red ): http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .html (Authoritative) http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .pdf Use symbols for the revision marking, in addition to color. This is important for TC members who are color blind or who are printing the document out on a black and white printer. I'd look at the DITAVAL files that we use for the errata version of the spec. There are extra spaces before some instances of the word component . I think changing instances of the word elements to components makes this document read VERY strangely. I am not on-board with this change , especially when the references are t o XDITA or XDITA. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 1/18/2018 1:21 PM, Carlos Evia wrote: Document Name : Lightweight DITA: An Introduction Description Marked version with changes implemented after public review #1. Thanks to Alan Houser for the transform. Download Latest Revision Public Download Link Submitter : Dr. Carlos Evia Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2018-01-18 10:20:42

Regarding this comment from Kris: > I think changing instances of the word "elements" to "components" makes this document read VERY strangely. I am not on-board with this change, especially when the references are to XDITA or XDITA. I assume that was meant to say XDITA or HDITA, which both have elements. But beyond that ... I think I have to agree that while "components" sounds accurate conceptually, when I read it in context, it's kind of jarring. That's especially true where we refer to "a subset of components in DITA 1.3" and I thought DITA 1.3 components were literally the different packages + grammar zip -- see the usage under "Additional artifacts": http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/dita-v1.3-errata01-os-part1-base-complete.html There are a few other uses -- our terminology topic lays out terms that "define components of the DITA standard". There's an actual element named <component>. Almost all remaining uses in the spec are part of examples, mostly for the delayed-conref-resolution domain. There is only one other instance I can find that seems more in line with the usage in the committee note, in the topic about single sourcing, which refers to "document components including paragraphs, lists, and tables": http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/archSpec/base/single-sourcing.html#single_sourcing Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---01/18/2018 01:21:58 PM---The subtitle should be "Committee Note 01" The date needs to be the date on which the TC will vote o From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org Date: 01/18/2018 01:21 PM Subject: [dita] Feedback about "Lightweight DITA: An Introduction" change-marked draft Sent by: <dita@lists.oasis-open.org> The subtitle should be "Committee Note 01" The date needs to be the date on which the TC will vote on the committee note: 23 January 2018 The file name should be "LwDITA-v1.0-cn01". (The easiest way to handle this is to rename the DITA map.) In "Specification URIs": The content currently in "This version" should move to "Previous version". The URLs for "This version" need to be as follows (changes indicated in red ): http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .html (Authoritative) http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .pdf Use symbols for the revision marking, in addition to color. This is important for TC members who are color blind or who are printing the document out on a black and white printer. I'd look at the DITAVAL files that we use for the errata version of the spec. There are extra spaces before some instances of the word "component". I think changing instances of the word "elements" to "components" makes this document read VERY strangely. I am not on-board with this change, especially when the references are to XDITA or XDITA. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 1/18/2018 1:21 PM, Carlos Evia wrote: Document Name : Lightweight DITA: An Introduction Description Marked version with changes implemented after public review #1. Thanks to Alan Houser for the transform. Download Latest Revision Public Download Link Submitter : Dr. Carlos Evia Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2018-01-18 10:20:42 --------------------------------------------------------------------- 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

1. A few of the URLs in the references section can be shortened by eliminating needless, ugly parameters:   [LwDITA-cross-format-content] https://www.slideshare.net/mpriestley/crossformat-content-with-lightweight-dita   [LwDITA-Easy-Way] https://dl.acm.org/citation.cfm?id=3121204   [LwDITA-pre/overview] http://www.slideshare.net/mpriestley/lightweight-dita-a-preoverview     2. In section 2, how about "common ground" instead of "common denominator"? The phrase "the common denominator" sets off math-nerd alarm bells. I don't like seeing terminology borrowed and imprecisely jargonized. (There's not just one "common denominator" of a set of numbers; there are infinitely many. There is a *least* common denominator, but that phrase doesn't sound as good when borrowed here.)     3. Re: "element" vs. "component" I almost completely agree with what Kris and Robert have said already. However, there is at least one occurrence of "components" that would NOT be better restored to say "elements":                   Section 4.1: "LwDITA uses a subset of the topic components that are available in DITA 1.3."   To me the phrase "topic elements" means <topic>, <concept>, <task>, etc.   4. Btw, if we should conclude that "components" is preferable after all, then more cleanup of the document is required to eliminate "elements" and make the terminology consistent. For example, there are two paragraphs in Section 4.3 that have a confusing mix of "elements" and "components" right now.     5. I think I missed whatever discussion/feedback led to the use of the word "components" to begin with. Is the problem with "elements" that Markdown/MDITA doesn't have them? How about using the word "structures" in its place in that case? I have no real experience with Markdown but "structures" seems to read OK to me in a couple of places where "components" occurs in both Section 5.3 and 5.3.2. (I have not considered it elsewhere. I like "elements".)   mag       From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Robert D Anderson Sent: January 18, 2018 11:39 AM To: Kristen James Eberlein Cc: dita@lists.oasis-open.org Subject: Re: [dita] Feedback about "Lightweight DITA: An Introduction" change-marked draft   Regarding this comment from Kris: > I think changing instances of the word "elements" to "components" makes this document read VERY strangely. I am not on-board with this change, especially when the references are to XDITA or XDITA. I assume that was meant to say XDITA or HDITA, which both have elements. But beyond that ... I think I have to agree that while "components" sounds accurate conceptually, when I read it in context, it's kind of jarring. That's especially true where we refer to "a subset of components in DITA 1.3" and I thought DITA 1.3 components were literally the different packages + grammar zip -- see the usage under "Additional artifacts": http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/dita-v1.3-errata01-os-part1-base-complete.html There are a few other uses -- our terminology topic lays out terms that "define components of the DITA standard". There's an actual element named <component>. Almost all remaining uses in the spec are part of examples, mostly for the delayed-conref-resolution domain. There is only one other instance I can find that seems more in line with the usage in the committee note, in the topic about single sourcing, which refers to "document components including paragraphs, lists, and tables": http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/archSpec/base/single-sourcing.html#single_sourcing Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---01/18/2018 01:21:58 PM---The subtitle should be "Committee Note 01" The date needs to be the date on which the TC will vote o From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org Date: 01/18/2018 01:21 PM Subject: [dita] Feedback about "Lightweight DITA: An Introduction" change-marked draft Sent by: <dita@lists.oasis-open.org>   The subtitle should be "Committee Note 01" The date needs to be the date on which the TC will vote on the committee note: 23 January 2018 The file name should be "LwDITA-v1.0-cn01". (The easiest way to handle this is to rename the DITA map.) In "Specification URIs": The content currently in "This version" should move to "Previous version". The URLs for "This version" need to be as follows (changes indicated in red ): http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .html (Authoritative) http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .pdf Use symbols for the revision marking, in addition to color. This is important for TC members who are color blind or who are printing the document out on a black and white printer. I'd look at the DITAVAL files that we use for the errata version of the spec. There are extra spaces before some instances of the word "component". I think changing instances of the word "elements" to "components" makes this document read VERY strangely. I am not on-board with this change, especially when the references are to XDITA or XDITA. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 1/18/2018 1:21 PM, Carlos Evia wrote: Document Name : Lightweight DITA: An Introduction Description Marked version with changes implemented after public review #1. Thanks to Alan Houser for the transform. Download Latest Revision Public Download Link Submitter : Dr. Carlos Evia Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2018-01-18 10:20:42 --------------------------------------------------------------------- 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

Based on conversations with Carlos Evia, Alan Houser, and Robert Anderson, I made revisions to the LwDITA committee note. Alan or others, can you do a sanity check? Tom, your e-mail hit the list after I'd done the rework. I think markup structures is a better (and more accurate) way to refer to LwDITA components . Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 1/18/2018 2:38 PM, Robert D Anderson wrote: Regarding this comment from Kris: > I think changing instances of the word elements to components makes this document read VERY strangely. I am not on-board with this change, especially when the references are to XDITA or XDITA. I assume that was meant to say XDITA or HDITA, which both have elements. But beyond that ... I think I have to agree that while components sounds accurate conceptually, when I read it in context, it's kind of jarring. That's especially true where we refer to a subset of components in DITA 1.3 and I thought DITA 1.3 components were literally the different packages + grammar zip -- see the usage under Additional artifacts : http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/dita-v1.3-errata01-os-part1-base-complete.html There are a few other uses -- our terminology topic lays out terms that define components of the DITA standard . There's an actual element named <component>. Almost all remaining uses in the spec are part of examples, mostly for the delayed-conref-resolution domain. There is only one other instance I can find that seems more in line with the usage in the committee note, in the topic about single sourcing, which refers to document components including paragraphs, lists, and tables : http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/archSpec/base/single-sourcing.html#single_sourcing Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---01/18/2018 01:21:58 PM---The subtitle should be Committee Note 01 The date needs to be the date on which the TC will vote o From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org Date: 01/18/2018 01:21 PM Subject: [dita] Feedback about Lightweight DITA: An Introduction change-marked draft Sent by: <dita@lists.oasis-open.org> The subtitle should be Committee Note 01 The date needs to be the date on which the TC will vote on the committee note: 23 January 2018 The file name should be LwDITA-v1.0-cn01 . (The easiest way to handle this is to rename the DITA map.) In Specification URIs : The content currently in This version should move to Previous version . The URLs for This version need to be as follows (changes indicated in red ): http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .html (Authoritative) http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .pdf Use symbols for the revision marking, in addition to color. This is important for TC members who are color blind or who are printing the document out on a black and white printer. I'd look at the DITAVAL files that we use for the errata version of the spec. There are extra spaces before some instances of the word component . I think changing instances of the word elements to components makes this document read VERY strangely. I am not on-board with this change, especially when the references are to XDITA or XDITA. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 1/18/2018 1:21 PM, Carlos Evia wrote: Document Name : Lightweight DITA: An Introduction Description Marked version with changes implemented after public review #1. Thanks to Alan Houser for the transform. Download Latest Revision Public Download Link Submitter : Dr. Carlos Evia Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2018-01-18 10:20:42 --------------------------------------------------------------------- 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 Attachment: LwDITA-v1.0-cnprd01.pdf Description: Adobe PDF document

Those revision marks with the extra square brackets are eye-catching, all right.   There are revision marks in the middle of some hyperlink text (hence blue not red) that do not have the square brackets: right at the end of Section 4.1.   I confess to not giving careful consideration to every single occurrence of "content component" vs. "element type" etc. in this draft.   mag       From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Kristen James Eberlein Sent: January 18, 2018 2:28 PM To: Robert D Anderson Cc: dita@lists.oasis-open.org Subject: Re: [dita] Feedback about "Lightweight DITA: An Introduction" change-marked draft   Based on conversations with Carlos Evia, Alan Houser, and Robert Anderson, I made revisions to the LwDITA committee note. Alan or others, can you do a sanity check? Tom, your e-mail hit the list after I'd done the rework. I think "markup structures" is a better (and more accurate) way to refer to "LwDITA components". Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 1/18/2018 2:38 PM, Robert D Anderson wrote: Regarding this comment from Kris: > I think changing instances of the word "elements" to "components" makes this document read VERY strangely. I am not on-board with this change, especially when the references are to XDITA or XDITA. I assume that was meant to say XDITA or HDITA, which both have elements. But beyond that ... I think I have to agree that while "components" sounds accurate conceptually, when I read it in context, it's kind of jarring. That's especially true where we refer to "a subset of components in DITA 1.3" and I thought DITA 1.3 components were literally the different packages + grammar zip -- see the usage under "Additional artifacts": http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/dita-v1.3-errata01-os-part1-base-complete.html There are a few other uses -- our terminology topic lays out terms that "define components of the DITA standard". There's an actual element named <component>. Almost all remaining uses in the spec are part of examples, mostly for the delayed-conref-resolution domain. There is only one other instance I can find that seems more in line with the usage in the committee note, in the topic about single sourcing, which refers to "document components including paragraphs, lists, and tables": http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/archSpec/base/single-sourcing.html#single_sourcing Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: robander@us.ibm.com Digital Services Group 11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA Kristen James Eberlein ---01/18/2018 01:21:58 PM---The subtitle should be "Committee Note 01" The date needs to be the date on which the TC will vote o From: Kristen James Eberlein <kris@eberleinconsulting.com> To: dita@lists.oasis-open.org Date: 01/18/2018 01:21 PM Subject: [dita] Feedback about "Lightweight DITA: An Introduction" change-marked draft Sent by: <dita@lists.oasis-open.org>   The subtitle should be "Committee Note 01" The date needs to be the date on which the TC will vote on the committee note: 23 January 2018 The file name should be "LwDITA-v1.0-cn01". (The easiest way to handle this is to rename the DITA map.) In "Specification URIs": The content currently in "This version" should move to "Previous version". The URLs for "This version" need to be as follows (changes indicated in red ): http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .html (Authoritative) http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .pdf Use symbols for the revision marking, in addition to color. This is important for TC members who are color blind or who are printing the document out on a black and white printer. I'd look at the DITAVAL files that we use for the errata version of the spec. There are extra spaces before some instances of the word "component". I think changing instances of the word "elements" to "components" makes this document read VERY strangely. I am not on-board with this change, especially when the references are to XDITA or XDITA. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 1/18/2018 1:21 PM, Carlos Evia wrote: Document Name : Lightweight DITA: An Introduction Description Marked version with changes implemented after public review #1. Thanks to Alan Houser for the transform. Download Latest Revision Public Download Link Submitter : Dr. Carlos Evia Group : OASIS Darwin Information Typing Architecture (DITA) TC Folder : Drafts Date submitted : 2018-01-18 10:20:42 --------------------------------------------------------------------- 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  

Hi Kris, Thanks for your thorough review! I had one technical issue with the build. I began with the following ditaval directive:   <revprop action= color= red val= public-review-01 >     <startflag><alt-text>?</alt-text></startflag>     <endflag><alt-text>?</alt-text></endflag>   </revprop> My (FOP-based) PDF build rendered the symbols as octothorps, so I removed the <startflag> and <endflag> directives from the ditaval. I concur that symbols are desirable for marking changes. If you or anybody else knows the cause of the behavior I'm seeing, I would be grateful. -Alan On 1/18/18 2:21 PM, Kristen James Eberlein wrote: The subtitle should be Committee Note 01 The date needs to be the date on which the TC will vote on the committee note: 23 January 2018 The file name should be LwDITA-v1.0-cn01 . (The easiest way to handle this is to rename the DITA map.) In Specification URIs : The content currently in This version should move to Previous version . The URLs for This version need to be as follows (changes indicated in red ): http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .html (Authoritative) http://docs.oasis-open.org/dita/LwDITA/v1.0/ cnd01 / LwDITA-v1.0-cn01 .pdf Use symbols for the revision marking, in addition to color. This is important for TC members who are color blind or who are printing the document out on a black and white printer. I'd look at the DITAVAL files that we use for the errata version of the spec. There are extra spaces before some instances of the word component . I think changing instances of the word elements to components makes this document read VERY strangely. I am not on-board with this change , especially when the references are t o XDITA or XDITA. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) <snip>