Review of the "DITA 1.3: A to Z article"

I agree with the comments that Chris Nitchie and Tom Magliery
    provided to the DITA TC mailing list

    

    Overall, I think this is a good and welcome article. There are some
    technical inaccuracies that should be fixed before it is released
    for general use. I'll split my comments into two categories below:
    "Things that need to be fixed" and "General comments".

    

    Things that need to be fixed

      
    
      
The date on the cover and footer does not match the
        date of the latest revision in the Document History.

      
deliveryTarget: 

      

      
        
Change "information architects can use subjectScheme
          attributes to control @deliveryTarget values" to "information
          architects can use subjectScheme maps to control the values
          for the @deliveryTarget attribute."

        
Change "it allows information architects to preprocess
          content targeted for specific output types" to "it allows
          information architects to target content for specific output
          types." 

        

      
      
Filtering Attributes Can Now Be Grouped: The content
        here is quite off. It's always (DITA 1.0 and forward) been
        possible to have audience="administrator programmer"; that's NOT
        new in DITA 1.3. I suggest conferring with Robert Anderson to
        clarify the use cases for grouping filtering
        attributes -- that's what is new in 1.3 -- it's not simple and
        will be difficult to explain for a non-technical audience.

      
Learning and Training Specialization: The
        statement "In DITA 1.2, writer were restricted to creating a
        single paragraph for question-and-answer exchanges" is
        misleading. Yes, it was a single element specialized from
        <p>. But the problem was that it allowed ONLY phrase-level
        content -- no figures, lists, tables, etc. For 1.3, the new
        element is specialized from <div> and so allows everything
        that can be contained within <div>: multiple paragraphs,
        lists, figures, etc.

      

    
    General comments

      
    
      
Suggest that the title simply be changed to "DITA 1.3 from
        A-Z"

      
Suggest adding a revision to the Document History: "Edits
        based on feedback from the OASIS DITA Technical Committee."

      
The TOC uses "init-style capitalization," but there are a few
        noticeable exceptions: "Key scope," "Sorting element," and
        "Table element."

      
Branch Filtering: The statement "[<ditavalref>] can
        operate at multiple levels with more than one behaviour" is
        unclear.

      
The term "information architects is capitalized in some places
        and not in others. Pick one convention and stick with it.

    
    
I did no have time to go through the entire article.

    

    
-- 

      Best,

      Kris

      

      Kristen James Eberlein

      Chair, OASIS DITA Technical Committee

      Principal consultant, Eberlein Consulting

      www.eberleinconsulting.com

      +1 919 682-2290; kriseberlein (skype)