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


Help: OASIS Mailing Lists Help | MarkMail Help

dita-lightweight-dita message

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

Subject: Response to Deb Bissantz's review (Was "Re: Fwd: LwDITA Draft document")

Deb, thanks so very much for your thoughtful review. Please see my comments below.


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

On 12/30/2016 11:04 AM, Kristen James Eberlein wrote:



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

-------- Forwarded Message --------
Subject: LwDITA Draft document
Date: Fri, 30 Dec 2016 15:42:51 +0000
From: Debra Bissantz <dbissantz@healthwise.org>
To: Kristen James Eberlein <kris@eberleinconsulting.com>


I looked over the document and have the following comments.


1.      Throughout the document, there is inconsistent use of LwDITA and Lightweight DITA.

<kje>Yes, Carlos Evia and I -- so far the only authors/editors -- have different preferences. Carlos likes to use the abbreviation, whereas I prefer to spell it out. Obviously we'll need to settle this style point.</kje>

2.      Is LwDITA considered a stepping stone to full DITA? The document mentions that LwDITA is an entry point, but I don’t see any mention of how or when to move from LwDITA to full DITA.

<kje>I would imagine that some folks will start and stay with Lightweight DITA. Others will start with Lightweight DITA and later move to full DITA in order to have a wider range of elements and authoring options. Do you think that we need to address "how or when to move from LwDITA to full DITA" in this committee note? As a voting TC member, would you like to know what the plan is for that regardless of whether it is content for the final committee note?</kje>

3.      P7, Section 2.1 – I agree with changing the title of section 2.1 to Simplified Structure.


4.      P10, Section 3.2 – The list of inline elements does not include underline or preformatted text. Is preformatted text a block element?

<kje>Have added underline to the list of inline elements. Yes, preformatted text (<pre>) is a block element; it is the specialization basis for <codeblock>. Do you think that we need to add here information about what block elements are part of Lightweight DITA?</kje>

5.      P10, Section 3.3 – The list of element where @conref is supported include <li>. I wonder why if all <li> must have a <p> and @conref is supported on <p>.

<kje>I wasn't not involved in this decision, but I certainly see a use case for reusing a <li> element, especially as it might include multiple paragraphs or a paragraph and a list or so forth.</kje>

6.      P12, Section 3.5 – If I am a new to DITA, I would find this section confusing or overwhelming. I understand the need for specialization, but as a beginner, I’m not sure that I want to know about that at this point in the document. I think this section belongs in Section 5, where the information seems to be duplicated. You could include a reference to Section 5 from 3.

<kje>We might well want to reconsider the structure at a later date, but for now there are solid reasons for the organization:
  1. The current audience is very much the voting members of the DITA TC and other experienced DITA users. Obviously, that will change at a later point in the development of the committee note, but right now the committee note is serving to lead us towards a formal proposal for Lightweight DITA.
  2. All the topics in section 3 are intended to touch on the fundamental design points of Lightweight DITA, which certainly includes a different specialization model than full DITA.
  3. The plan for section 5 is to include the following items (not the current content, which is a simple cut-and-paste from Lightweight DITA GitHub repo):
    1. Brief description of the template-based specialization model
    2. Example of a simple Lightweight DITA topic that would be input to a tool
    3. Example of the generated grammar file
    4. General description of the algorithm that a tool would use to construct the grammar file for a specialization</kje>

7.      P16, Section 4.2.1 – Typo in 3rd bullet, I think (MS) should be (LMS).


8.      P19, Section 5 – This section duplicates section 3.5. I think all of the specialization information should be in one place.

9.      P24, Section A.3 – Does LwDITA rely on the @class attribute? It is not in the table of attributes.


Let me know if you have any questions or need further explanations.


Deb Bissantz

Technical Communication Architect/Writer

dbissantz@healthwise.org  |  www.healthwise.org

208.331.8729 office


Healthwise helps people make better health decisions


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

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