RE: [dita] some comemnts on the Draft DITA 1.2 architecture spec.

I 
think I'm starting to agree with you Jeff: the entire section should be called 
"Customization," and specialization should be considered a species of 
customization.

 

So the 
distinction is between using a vendor implementation of DITA off the shelf and 
out of the box without modification - which some, perhaps many implementors are 
going to do - and "customizing" that vendor implementation to fit customer 
requirements.

 

What 
this section needs to do in terms of conformance is to spell out vendor and 
implementor responsibilities for each kind of customization to achieve an 
interoperable, or at least a harmless, system (to use the RFC phraseology 
on conformance statements), i.e.:

  
Shells: Vendors MUST support, implementors SHOULD 
  use

  
Constraints: Vendors MUST support, implementors SHOULD 
  use

  
Specialization: Vendors MUST support, implementors MAY 
  use

  
Variation (or whatever we call customization that changes some 
  parts of the DITA vocabulary or violates some of its architectural principles, 
  yet produces valid XML, and perhaps even valid DITA document instances): 
  Vendors SHOULD support, implementors MAY use

 

  
-----Original Message-----
From: Ogden, Jeff 
  [mailto:]
Sent: Tuesday, June 30, 2009 11:23 
  AM
To: JoAnn Hackos; Dana Spradley; dita
Subject: RE: 
  [dita] some comemnts on the Draft DITA 1.2 architecture 
  spec.

  

  
I don’t know if there is a 
  less “drastic” and more appropriate term than “customization”, but I’m sure 
  that “specialization” isn’t the right word to use when someone creates a new 
  document type shell.  Specializations create new DITA types. Modifying a 
  document type shell doesn’t create a new DITA type, but just assembles 
  existing DITA types for use.  One of the goals of the constraints 
  proposal as I remember it was to allow customization without requiring 
  specialization.

  
 

  
I’ve always thought of 
  “specialization” as being a subset of the larger class of 
  customizations:

  
 

  
1)      
  Customization

  
1.1) 
   Specialization

  
1.1.1)       
  Structural 
  Specialization

  
1.1.2)       
  Domain 
  Specialization

  
1.2) 
   Customized 
  Document type shells

  
1.3) 
   Customized 
  Processing

  
1.3.1) Transformations

  
1.3.2) Stylesheet 
  processing/formatting

  
 

  
Part of the problem here may 
  be that we don’t have good names for 1.2 and 1.3.

  
 

  
    
  -Jeff

  
                                
  

  
 

  

  

  

  
From: JoAnn Hackos 
  [mailto:] 
Sent: Tuesday, June 30, 2009 
  1:52 PM
To: Dana Spradley; Ogden, Jeff; dita
Subject: RE: 
  [dita] some comemnts on the Draft DITA 1.2 architecture 
  spec.

  
 

  
Should 
  not we always refer to such changes as “specializations” rather than 
  “customizations”?

  
 

  

  
JoAnn Hackos 
  PhD

  
President

  
Comtech Services, 
  Inc.

  


  
Skype 
  joannhackos

  
 

  

  

  
  

  
From: Dana Spradley 
  [mailto:] 
Sent: Tuesday, June 30, 2009 
  11:46 AM
To: Ogden, Jeff; dita
Subject: RE: [dita] some 
  comemnts on the Draft DITA 1.2 architecture spec.

  
 

  

  
Is 
  "customized"/"customization" really appropriate here? Are is this something 
  we're considering less drastic than customization?

  
    
-----Original 
    Message-----
From: Ogden, Jeff 
    [mailto:]
Sent: Monday, June 29, 2009 7:37 
    PM
To: dita
Subject: [dita] some comemnts on the Draft 
    DITA 1.2 architecture spec.

    
Some suggestions 
    with additions underlined and 
    blue and deletions strikeout and 
    red:

    
 

    Concrete 
    document types
    
A 
    given DITA map or topic document is governed by a concrete document type 
    that defines the set of structural modules (topic or map types), domain 
    modules, and constraints modules that the map or topic can 
    use, 
    as well as the degree of topic nesting that is allowed within the document 
    type. 
    While the DITA specification includes a starter set of concrete document 
    types for common combinations of modules, those document types are not 
    mandatory and, for most 
    many 
    DITA users, include more things 
    definitions 
    than they need for their documents. In 
    general, any production use of DITA involves definition of 
    the 
    DITA 
    users are encouraged to create their own customized concrete document types 
    that include the set 
    of modules best suited to local requirements. This always 
    customization 
    requires 
    the creation of "local shell" document types, even if all they do is omit 
    unneeded modules or apply constraints to the standard DITA-defined 
    vocabulary. Thus 
    you should expect in any production use of DITA that the first step is to 
    define local concrete document types.

    
Note: The 
    simplest form of local shell is an unaltered copy of one of the DITA 
    TC-provided shells to which is associated a new public identifier or 
    absolute 
    URI, 
    reflecting ownership of the new shell by its creator. For example, to create 
    a local shell DTD for generic maps, simply copy the TC-provided file 
    "map.dtd" to a local location, possibly using a new name for the file to 
    avoid confusion, and create an entity mapping catalog that binds the new 
    copy of map.dtd to a public ID or absolute 
    URI you define, e.g. PUBLIC 
    "-//example.com/DTD DITA NewMap//EN or urn:public:example.dom/dita/doctypes/map 
    urn:example.com:names:dita:xsd:newmap.xsd.

    
Concrete 
    DITA document types must 
    SHOULD 
    follow the implementation design patterns defined in this specification. 
    This ensures consistency of implementation and also serves to make the task 
    of creating concrete document types almost entirely 
    mechanical.

    
·         
    Modularization 
    and integration of design
Specialization 
    hierarchies are implemented as sets of vocabulary modules, each of which 
    declares the markup and entities that are unique to a specialization. The 
    modules must be integrated into a document type before they can be 
    used.

    
·         
    DTD 
    syntax specialization design patterns
To 
    be extensible and backward compatible, DITA 
    requires that a 
    DTD implementation of structural and domain specialization modules 
    SHOULD 
    conform 
    to well-defined 
    the 
    design patterns used 
    for the DTD shells included as part of the DITA specification and described 
    in this topic.

    
·         
    XSD 
    schema specialization design patterns
To 
    be extensible and backward compatible, DITA 
    requires that an 
    XML schema implementation of structural and domain specialization modules 
    SHOULD 
    conform to well-defined 
    the design patterns used 
    for the XML schema shells included as part fo the DITA specification and 
    described in this topic.

    
While 
    we can require that customized concrete document types follow the rules as 
    outlined in the DITA 1.2 speciication, I don’t think that we can require 
    that they follow the design patterns or that the design patterns are well 
    enough specified to allow them to be a requirement.  At this stage I 
    think the design patters are more of a “best practice” than a requirement 
    that must be followed and so they SHOULD be followed rather than MUST be 
    followed.

    
 

    
It seems likely 
    that the section on “Modularization and integration of design” should be 
    deleted since it is almost entirely repeating information that has been 
    provided in the main section..

    
 

    
 

    

    
 

    
 

    
 

    
For the page 
    dita-1.2-spec/arch/20090617/createConstraintsDomainSpec.html 
    :

    
 

    
I don’t have any 
    comments on the main topic other than to say that it feels as of this topic 
    is saying the same thing two or even three times and that probably isn’t a 
    good idea.