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

            

              To: 
              Kristen James Eberlein <>
            

          
        
        

        

        
        
        
        

          
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:

      
    
      
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.

      
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.

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

      
        
Brief description of the
              template-based specialization model

        
Example of a simple Lightweight
              DITA topic that would be input to a tool

        
Example of the generated grammar
              file

        
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

          
  |  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