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.

Best,
Kris

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

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

FYI


Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+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>


Kris,

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.

<kje>Done.</kje>

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

<kje>Done</kje>

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]